Provides tools for reading, creating, searching, and managing notes in an Obsidian vault through the Local REST API plugin, enabling operations like listing notes by directory, reading note content, creating/updating notes, and performing text searches.
Obsidian MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your Obsidian vault. This server provides tools for reading, creating, searching, and managing notes in Obsidian through the Local REST API plugin.
Features
- 📖 Read & write notes - Full access to your Obsidian vault with automatic overwrite protection
- 🔍 Smart search - Find notes by content, tags, or modification date
- 📁 Browse vault - List and navigate your notes by directory
- 🏷️ Tag management - Add, remove, and organize tags in frontmatter
- 📊 Note insights - Get statistics like word count and link analysis
- 🎯 AI-optimized - Clear error messages and smart defaults for better AI interactions
- 🔒 Secure - API key authentication with local-only connections
Prerequisites
- Obsidian with the Local REST API plugin installed and enabled
- Python 3.10+ installed on your system
- Node.js (optional, for running MCP Inspector)
Installation
Quick Install
- Install and configure Obsidian:
- Install the Local REST API plugin in Obsidian
- Enable the plugin in Settings > Community plugins
- Go to Settings > Local REST API
- Copy your API key (you'll need this for step 2)
- Configure your AI tool:Edit your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add to your Cursor settings:
- Project-specific:
.cursor/mcp.json
in your project directory - Global:
~/.cursor/mcp.json
in your home directory
Then: Open Settings → Cursor Settings → Enable MCP
Edit your Windsurf config file:
- Location:
~/.codeium/windsurf/mcp_config.json
Then: Open Windsurf Settings → Advanced Settings → Cascade → Add Server → Refresh
Replace
your-api-key-here
with the API key you copied from Obsidian. - macOS:
- Restart your AI tool to load the new configuration.
That's it! The server will now be available in your AI tool with access to your Obsidian vault.
Note: This uses
uvx
which automatically downloads and runs the server in an isolated environment. Most users won't need to install anything else. If you don't haveuv
installed, you can also usepipx install obsidian-mcp
and change the command to"obsidian-mcp"
in the config.
Try It Out
Here are some example prompts to get started:
- "Show me all notes I modified this week"
- "Create a new daily note for today with my meeting agenda"
- "Search for all notes about project planning"
- "Read my Ideas/startup.md note"
Development Installation
- Clone the repository:
- Set up Python environment:
- Install dependencies:
- Set up Obsidian Local REST API:
- Install the Local REST API plugin in Obsidian
- Enable the plugin in Obsidian settings
- Copy the API key from the plugin settings
- Note the port number (default: 27124)
- Configure environment variables:
- Add to Claude Desktop (for development):Edit your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
Project Structure
Available Tools
Note Management
read_note
Read the content and metadata of a specific note.
Parameters:
path
: Path to the note (e.g., "Daily/2024-01-15.md")
Returns:
create_note
Create a new note or update an existing one.
Parameters:
path
: Path where the note should be createdcontent
: Markdown content of the noteoverwrite
(default:false
): Whether to overwrite existing notes
update_note
Update the content of an existing note.
⚠️ IMPORTANT: By default, this tool REPLACES the entire note content. Always read the note first if you need to preserve existing content.
Parameters:
path
: Path to the note to updatecontent
: New markdown content (REPLACES existing content unless using append)create_if_not_exists
(default:false
): Create if doesn't existmerge_strategy
(default:"replace"
): How to handle content"replace"
: Overwrites entire note content (default)"append"
: Adds new content to the end of existing content
Safe Update Pattern:
delete_note
Delete a note from the vault.
Parameters:
path
: Path to the note to delete
Search and Discovery
search_notes
Search for notes containing specific text.
Parameters:
query
: Search query (supports Obsidian search syntax)context_length
(default:100
): Number of characters to show around matches
Note: Search functionality may have connectivity issues with some REST API configurations.
search_by_date
Search for notes by creation or modification date.
Parameters:
date_type
(default:"modified"
): Either "created" or "modified"days_ago
(default:7
): Number of days to look backoperator
(default:"within"
): Either "within" (last N days) or "exactly" (exactly N days ago)
Returns:
Example usage:
- "Show me all notes modified this week" →
search_by_date("modified", 7, "within")
- "Find notes created in the last 30 days" →
search_by_date("created", 30, "within")
- "What notes were modified exactly 2 days ago?" →
search_by_date("modified", 2, "exactly")
list_notes
List notes in your vault with optional recursive traversal.
Parameters:
directory
(optional): Specific directory to list (e.g., "Daily", "Projects")recursive
(default:true
): List all notes recursively
Returns:
Organization
move_note
Move a note to a new location.
Parameters:
source_path
: Current path of the notedestination_path
: New path for the noteupdate_links
(default:true
): Update links in other notes (future enhancement)
add_tags
Add tags to a note's frontmatter.
Parameters:
path
: Path to the notetags
: List of tags to add (without # prefix)
remove_tags
Remove tags from a note's frontmatter.
Parameters:
path
: Path to the notetags
: List of tags to remove
get_note_info
Get metadata and statistics about a note without retrieving its full content.
Parameters:
path
: Path to the note
Returns:
Testing
Running Tests
Testing with MCP Inspector
- Ensure Obsidian is running with the Local REST API plugin enabled
- Run the MCP Inspector:
- Open the Inspector UI at
http://localhost:5173
- Test the tools interactively with your actual vault
Integration with Claude Desktop
For development installations, see the Development Installation section above.
Enhanced Error Handling
The server provides detailed, actionable error messages to help AI systems recover from errors:
Example Error Messages
Invalid Path:
Empty Search Query:
Invalid Date Parameters:
Troubleshooting
"Connection refused" error
- Ensure Obsidian is running
- Verify the Local REST API plugin is enabled
- Check that the port matches (default: 27124)
- Confirm the API key is correct
- The enhanced error will show the exact URL and port being used
"Certificate verify failed" error
- This is expected with the Local REST API's self-signed certificate
- The server handles this automatically
"Module not found" error
- Ensure your virtual environment is activated
- Run from the project root:
python -m src.server
- Verify PYTHONPATH includes the project directory
Empty results when listing notes
- Specify a directory when using
list_notes
(e.g., "Daily", "Projects") - Root directory listing requires recursive implementation
- Check if notes are in subdirectories
Tags not updating
- Ensure notes have YAML frontmatter section
- Frontmatter must include a
tags:
field (even if empty)
Best Practices for AI Assistants
Preventing Data Loss
- Always read before updating: The
update_note
tool REPLACES content by default - Use append mode for additions: When adding to existing notes, use
merge_strategy="append"
- Check note existence: Use
read_note
to verify a note exists before modifying - Be explicit about overwrites: Only use
overwrite=true
when intentionally replacing content
Recommended Workflows
Safe note editing:
- Read the existing note first
- Modify the content as needed
- Update with the complete new content
Adding to daily notes:
- Use
merge_strategy="append"
to add entries without losing existing content
Creating new notes:
- Use
create_note
withoverwrite=false
(default) to prevent accidental overwrites
Security Considerations
- Keep your API key secret - never commit it to version control
- The server validates all paths to prevent directory traversal attacks
- All communication with Obsidian uses HTTPS (self-signed certificate)
- The server only accepts local connections through the REST API
Development
Code Style
- Uses FastMCP framework for MCP implementation
- Pydantic models for type safety and validation
- Modular architecture with separated concerns
- Comprehensive error handling and user-friendly messages
Adding New Tools
- Create tool function in appropriate module under
src/tools/
- Add Pydantic models if needed in
src/models/
- Register the tool in
src/server.py
with the@mcp.tool()
decorator - Include comprehensive docstrings
- Add tests in
tests/
- Test with MCP Inspector before deploying
Publishing (for maintainers)
To publish a new version to PyPI:
Users can then install and run with:
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-tool
) - Write tests for new functionality
- Ensure all tests pass
- Commit your changes (
git commit -m 'Add amazing tool'
) - Push to the branch (
git push origin feature/amazing-tool
) - Open a Pull Request
License
MIT License - see LICENSE file for details
Acknowledgments
- Anthropic for creating the Model Context Protocol
- Obsidian team for the amazing note-taking app
- coddingtonbear for the Local REST API plugin
- dsp-ant for the FastMCP framework
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables AI assistants like Claude to interact with your Obsidian vault through the Local REST API plugin, allowing reading, creating, searching, and managing notes.
Related MCP Servers
- -securityAlicense-qualityA local MCP server that enables AI applications like Claude Desktop to securely access and work with Obsidian vaults, providing capabilities for reading notes, executing templates, and performing semantic searches.Last updated -60TypeScriptMIT License
- -securityAlicense-qualityProvides a standardized interface for AI assistants to interact with Obsidian vaults through a local REST API, enabling reading, writing, searching, and managing notes.Last updated -37TypeScriptMIT License
- -securityFlicense-qualityThis project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.Last updated -5987JavaScript
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.Last updated -598TypeScriptISC License