Peter.Morton
8e2e8f858c
Fixed parameter quoting in file operations and search tools to handle
filenames and values containing spaces correctly.
Root Cause:
- Obsidian CLI requires quoting values with spaces: name="My Note"
- Previous implementation used unquoted format: name=My Note
- Shell would split on spaces, breaking multi-word filenames
Solution:
1. Created formatParam() helper in src/utils/cli-helpers.ts
- Always quotes parameter values: param="value"
- Handles spaces and special characters safely
2. Updated file-operations.ts (8 tools):
- All file/path/content/name parameters now quoted
- create, read, append, prepend, delete, move, rename, open
3. Updated search.ts (1 tool):
- query, path, format, limit parameters now quoted
- Fixes searches with multi-word queries
Changes:
- Before: cmdArgs.push(\`file=${name}\`)
- After: cmdArgs.push(formatParam('file', name))
Files changed:
- src/utils/cli-helpers.ts (new): formatParam() and buildCmdArgs() helpers
- src/tools/file-operations.ts: Use formatParam() for all parameters
- src/tools/search.ts: Use formatParam() for all parameters
Impact:
- File operations now work with multi-word filenames
- Search queries with spaces now work correctly
- Content parameters with newlines/special chars handled safely
Known Issue:
- links.ts, tags-aliases.ts, properties.ts still need similar fixes
- These tools have additional structural issues (wrong command names)
- Will be addressed in follow-up commit
Build: 0 errors
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Obsidian MCP Bundle
An MCP (Model Context Protocol) Bundle that exposes Obsidian CLI capabilities to AI assistants, enabling conversational note management through natural language.
Features
- 📝 File Operations: Create, read, update, delete notes
- 🔍 Search & Discovery: Full-text search, tag queries, backlink navigation
- ✅ Task Management: Create, update, and track tasks
- 🏷️ Properties & Metadata: Manage note properties, tags, and aliases
- 📅 Daily Notes: Create and navigate daily notes
- 🔖 Bookmarks: Manage bookmarked notes
- 🎨 Customization: Plugin and theme management
- 🔄 Vault Navigation: List files, folders, and navigate hierarchies
Installation
Prerequisites
- Node.js >= 18.0.0
- Obsidian CLI installed and configured
- Obsidian application installed
Install via Claude Desktop
- Download the latest
.mcpbfile from releases - Open Claude Desktop settings
- Add the bundle to your MCP servers configuration
- Configure your vault name in the settings
Manual Installation
# Install dependencies
npm install
# Build the bundle
npm run build
# Package as .mcpb file
npm run pack
Configuration
The bundle requires a vault_name parameter to target your Obsidian vault:
{
"mcpServers": {
"obsidian-mcp": {
"bundle": "path/to/obsidian-mcp.mcpb",
"user_config": {
"vault_name": "MyVault"
}
}
}
}
Usage Examples
With Claude Desktop
You: "Create a new note called 'Meeting Notes' with today's date"
Assistant: [Uses obsidian_create_note tool]
You: "Search for all notes about project planning"
Assistant: [Uses obsidian_search tool]
You: "Add a task to my daily note: Review PR #123"
Assistant: [Uses obsidian_add_task tool]
Available Tools
The bundle provides 95+ MCP tools covering:
- File Operations: create_note, read_note, append_to_note, delete_note, move_note, rename_note, open_note, get_file_info
- Search: search (content), search_tags, search_properties
- Links: get_backlinks, get_outbound_links, get_unresolved_links
- Tasks: add_task, list_tasks, update_task
- Properties: get_properties, add_property, update_property, remove_property
- Tags: get_tags, add_tag, remove_tag
- Navigation: list_files, list_folders, get_folder_info
- Daily Notes: create_daily_note, goto_daily_note
- And more: templates, bookmarks, plugins, themes, history, sync
See full tool documentation in the contracts/tools.md file.
Development
# Install dependencies
npm install
# Run in development mode (watch for changes)
npm run dev
# Run tests
npm test
# Validate tool descriptions
npm run validate-tools
# Build for production
npm run build
Architecture
- Transport: stdio (JSON-RPC over standard input/output)
- Validation: Zod schemas for all tool parameters
- Error Handling: Graceful error messages with actionable guidance
- Timeout Management: 30-second default timeout for CLI commands
- Logging: Sanitized stderr-only logging (no stdout pollution)
Performance
- File operations: < 3 seconds
- Search queries: < 5 seconds (vaults up to 10,000 notes)
- CLI timeout: 30 seconds (configurable per command)
Platform Support
- macOS
- Windows
- Linux
License
MIT
Contributing
Contributions are welcome! Please ensure:
- All tools follow MCP protocol standards
- Input validation uses Zod schemas
- Errors provide actionable messages
- Tests pass with
npm test - Tool descriptions are clear and complete
Troubleshooting
"Obsidian not running" error
Start the Obsidian application before using MCP tools.
"Vault not found" error
Ensure the vault_name in your configuration matches exactly (case-sensitive).
Timeout errors
Increase timeout in src/config/timeouts.ts for slow operations.