by j-shelfwood
Connect and manage Obsidian vaults with the Obsidian Local REST API for smarter note handling, semantic search, and seam
Connects AI agents to your Obsidian vault through the Local REST API plugin for advanced note searching, content retrieval, and knowledge analysis workflows.
Obsidian Local REST API is a community-built MCP server published by j-shelfwood that provides AI assistants with tools and capabilities via the Model Context Protocol. Connect and manage Obsidian vaults with the Obsidian Local REST API for smarter note handling, semantic search, and seam It is categorized under productivity.
You can install Obsidian Local REST API in your AI client of choice. Use the install panel on this page to get one-click setup for Cursor, Claude Desktop, VS Code, and other MCP-compatible clients. This server runs locally on your machine via the stdio transport.
MIT
Obsidian Local REST API is released under the MIT license. This is a permissive open-source license, meaning you can freely use, modify, and distribute the software.
Add new capabilities to Claude beyond text generation
Example
Access external data sources, execute code, interact with tools and services
Transform Claude from chatbot to action-taking agent
Provide Claude with access to relevant context and data
Example
Load project documentation, access knowledge bases, query databases
Get more accurate, context-aware responses
Automate multi-step workflows combining AI and external tools
Example
Research → Summarize → Create document → Send notification
Complete complex tasks end-to-end without manual steps
Share your MCP server with the developer community
We wired Obsidian Local REST API into a staging workspace; the listing’s GitHub and npm pointers saved time versus hunting across READMEs.
Strong directory entry: Obsidian Local REST API surfaces stars and publisher context so we could sanity-check maintenance before adopting.
According to our notes, Obsidian Local REST API benefits from clear Model Context Protocol framing — fewer ambiguous “AI plugin” claims.
Strong directory entry: Obsidian Local REST API surfaces stars and publisher context so we could sanity-check maintenance before adopting.
Obsidian Local REST API is among the better-indexed MCP projects we tried; the explainx.ai summary tracks the official description.
Obsidian Local REST API reduced integration guesswork — categories and install configs on the listing matched the upstream repo.
According to our notes, Obsidian Local REST API benefits from clear Model Context Protocol framing — fewer ambiguous “AI plugin” claims.
Obsidian Local REST API is among the better-indexed MCP projects we tried; the explainx.ai summary tracks the official description.
We evaluated Obsidian Local REST API against two servers with overlapping tools; this profile had the clearer scope statement.
We evaluated Obsidian Local REST API against two servers with overlapping tools; this profile had the clearer scope statement.
showing 1-10 of 49
An AI-Native MCP (Model Context Protocol) server that provides intelligent, task-oriented tools for interacting with Obsidian vaults through a local REST API.
This MCP server has been redesigned following AI-Native principles rather than simple API-to-tool mapping. Instead of exposing low-level CRUD operations, it provides high-level, task-oriented tools that LLMs can reason about more effectively.
| Old Approach (CRUD-Based) | New Approach (AI-Native) | Why Better |
|---|---|---|
list_files (returns everything) | list_directory(path, limit, offset) | Prevents context overflow with pagination |
create_file + update_file | write_file(path, content, mode) | Single tool handles create/update/append |
create_note + update_note | create_or_update_note(path, content, frontmatter) | Intelligent upsert removes decision complexity |
search_notes(query) | search_vault(query, scope, path_filter) | Precise, scopeable search with advanced filtering |
| (no equivalent) | get_daily_note(date) | High-level abstraction for common workflow |
| (no equivalent) | get_recent_notes(limit) | Task-oriented recent file access |
| (no equivalent) | find_related_notes(path, on) | Conceptual relationship discovery |
list_directoryPurpose: List directory contents with pagination to prevent context overflow
{
"path": "Projects/",
"recursive": false,
"limit": 20,
"offset": 0
}
AI Benefit: LLM can explore vault structure incrementally without overwhelming context
read_filePurpose: Read content of any file in the vault
{"path": "notes/meeting-notes.md"}
write_filePurpose: Write file with multiple modes - replaces separate create/update operations
{
"path": "notes/summary.md",
"content": "# Meeting Summary
...",
"mode": "append" // "overwrite", "append", "prepend"
}
AI Benefit: Single tool handles all write scenarios, removes ambiguity
delete_itemPurpose: Delete any file or directory
{"path": "old-notes/"}
create_or_update_notePurpose: Intelligent upsert - creates if missing, updates if exists
{
"path": "daily/2024-12-26",
"content": "## Tasks
- Review AI-native MCP design",
"frontmatter": {"tags": ["daily", "tasks"]}
}
AI Benefit: Eliminates "does this note exist?" decision tree
get_daily_notePurpose: Smart daily note retrieval with common naming patterns
{"date": "today"} // or "yesterday", "2024-12-26"
AI Benefit: Abstracts file system details and naming conventions
get_recent_notesPurpose: Get recently modified notes
{"limit": 5}
AI Benefit: Matches natural "what did I work on recently?" queries
search_vaultPurpose: Multi-scope search with advanced filtering
{
"query": "machine learning",
"scope": ["content", "filename", "tags"],
"path_filter": "research/"
}
AI Benefit: Precise, targeted search reduces noise
find_related_notesPurpose: Discover conceptual relationships between notes
{
"path": "ai-research.md",
"on": ["tags", "links"]
}
AI Benefit: Enables relationship-based workflows and serendipitous discovery
The server maintains backward compatibility with existing tools like get_note, list_notes, get_metadata_keys, etc.
npx obsidian-local-rest-api-mcp
# Clone the repository
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp
# Install dependencies with bun
bun install
# Build the project
bun run build
Set environment variables for API connection:
export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test" # Default URL (or http://localhost:8000 for non-Valet setups)
export OBSIDIAN_API_KEY="your-api-key" # Optional bearer token
# Development mode with auto-reload
bun run dev
# Production mode
bun run start
# Or run directly
node build/index.js
Add to your claude_desktop_config.json:
{
"mcpServers": {
"obsidian-vault": {
"command": "npx",
"args": ["obsidian-local-rest-api-mcp"],
"env": {
"OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
"OBSIDIAN_API_KEY": "your-api-key-if-needed"
}
}
}
}
Use the included .vscode/mcp.json configuration file.
# Watch mode for development
bun run dev
# Build TypeScript
bun run build
# Type checking
bun run tsc --noEmit
The server includes comprehensive error handling:
Errors are returned as MCP tool call responses with descriptive messages.
Enable debug logging by setting environment variables:
export DEBUG=1
export NODE_ENV=development
Server logs are written to stderr to avoid interfering with MCP protocol communication on stdout.
If your MCP client shows "Start Failed" or similar errors:
Test the server directly:
npx obsidian-local-rest-api-mcp --version
Should output the version number.
Test MCP protocol:
# Run our test script
node -e "
const { spawn } = require('child_process');
const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
child.stdout.on('data', d => console.log('OUT:', d.toString()));
child.stderr.on('data', d => console.log('ERR:', d.toString()));
setTimeout(() => {
child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'
'); setTimeout(() => child.kill(), 2000); }, 500); "
Should show initialization response.
3. **Check Environment Variables**:
- Ensure `OBSIDIAN_API_URL` points to a running Obsidian Local REST API
- Test the API directly: `curl http://obsidian-local-rest-api.test/api/files` (or your configured API URL)
4. **Verify Obsidian Local REST API**:
- Install and run [Obsidian Local REST API](https://github.com/j-shelfwood/obsidian-local-rest-api)
- Confirm it's accessible on the configured port
- Check if authentication is required
### Common Issues
**"Command not found"**: Make sure Node.js/npm is installed and npx is available
**"Connection refused"**: Obsidian Local REST API is not running or wrong URL
**Laravel Valet .test domains**: If using Laravel Valet, ensure your project directory name matches the .test domain (e.g., `obsidian-local-rest-api.test` for a project in `/obsidian-local-rest-api/`)
**"Unauthorized"**: Check if API key is required and properly configured
**"Timeout"**: Increase timeout in client configuration or check network connectivity
### Cherry Studio Configuration
For Cherry Studio, use these exact settings:
- **Name**: `obsidian-vault` (or any name you prefer)
- **Type**: `Standard Input/Output (stdio)`
- **Command**: `npx`
- **Arguments**: `obsidian-local-rest-api-mcp`
- **Environment Variables**:
- `OBSIDIAN_API_URL`: Your API URL (e.g., `http://obsidian-local-rest-api.test` for Laravel Valet)
- `OBSIDIAN_API_KEY`: Optional API key if authentication is required
- **Environment Variables**:
- `OBSIDIAN_API_URL`: `http://obsidian-local-rest-api.test` (or your API URL)
- `OBSIDIAN_API_KEY`: `your-api-key` (if required)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes with proper TypeScript types
4. Test with your Obsidian vault
5. Submit a pull request
## License
MIT
Prerequisites
Time Estimate
15-60 minutes depending on server complexity
Steps
Troubleshooting
✓ Do
✗ Don't
💡 Pro Tips
Architecture
Model Context Protocol standardizes how AI hosts (Claude, Cursor) communicate with external tools and data sources through server implementations.
Protocols
Compatibility
✓ Use when
Use when you need Claude to access external data, execute actions, or integrate with tools. Best for extending AI capabilities beyond conversation.
✗ Avoid when
Avoid when native integrations exist (use official APIs directly), for real-time critical systems, or when security/compliance requires zero external dependencies.