Uses .env files for server configuration, allowing users to set vault paths, daily note locations, server ports, and other settings through environment variables.
Works with Markdown files in the Obsidian vault, allowing creation, editing, and manipulation of Markdown content and frontmatter metadata.
Provides tools for interacting with an Obsidian vault, including reading and writing notes, managing note metadata, listing notes and folders, searching content, managing daily notes, and working with links, backlinks, and tags.
Obsidian MCP Tool Server
This project provides a Model Context Protocol (MCP) server that exposes tools for interacting with an Obsidian vault.
Table of Contents
Features
Allows MCP clients (like AI assistants) to:
Read and write notes
Manage note metadata (frontmatter)
List notes and folders
Search notes by content or metadata
Manage daily notes
Get outgoing links, backlinks, and tags
Installation
Clone the repository (if you haven't already):
# git clone <repository-url> # cd OMCPNavigate to the project directory:
cd /path/to/your/OMCPCreate a Python virtual environment (recommended to avoid dependency conflicts):
python -m venv .venvActivate the virtual environment:
On Windows PowerShell:
.venv\Scripts\Activate.ps1On Linux/macOS:
source .venv/bin/activate
(Your terminal prompt should now show
(.venv)
at the beginning)Install the package and its dependencies:
pip install .
Configuration
This server is configured using environment variables, which can be conveniently managed using a .env
file in the project root.
Copy the example file:
# From the project root directory (OMCP/) cp .env.example .env(On Windows, you might use
copy .env.example .env
)Edit the Open the newly created
.env
file in a text editor.Set This is the only required variable. Update it with the absolute path to your Obsidian vault. Use forward slashes (
/
) for paths, even on Windows.OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"Review Optional Settings: Adjust the other
OMCP_
variables for daily notes, server port, or backup directory if needed. Read the comments in the file for explanations.
(Alternatively, instead of using a
Running Manually (for Testing/Debugging)
While client applications like Claude Desktop will launch the server automatically using the configuration described below, you can also run the server manually from your terminal for direct testing or debugging.
Ensure Configuration is Done: Make sure you have created and configured your
.env
file as described in the Configuration section.Activate Virtual Environment:
# If not already active .venv\Scripts\Activate.ps1(Use
Run the server script:
(.venv) ...> python obsidian_mcp_server/main.py
The server will start and print the address it's listening on (e.g., http://127.0.0.1:8001
). You would typically press Ctrl+C
to stop it when finished testing.
Remember: If you intend to use this server with Claude Desktop or a similar launcher, you should not run it manually like this. Configure the client application instead (see next section), and it will handle starting and stopping the server process.
Client Configuration (Example: Claude Desktop)
Many MCP clients (like Claude Desktop) can launch server processes directly. To configure such a client, you typically need to edit its JSON configuration file (e.g., claude_desktop_config.json
on macOS/Linux, find the equivalent path on Windows under AppData
).
⚠️ Important JSON Formatting Rules:
JSON files do not support comments (remove any
//
or/* */
comments)All strings must be properly quoted with double quotes (
"
)Windows paths must use escaped backslashes (
\\
)Use a JSON validator (like jsonlint.com) to check your syntax
Here's an example entry to add under the mcpServers
key in the client's JSON configuration:
Key Points:
Replace the paths with the absolute paths relevant to your system
For Windows paths in the
command
andargs
fields:Use double backslashes (
\\
) for path separatorsInclude the
.exe
extension for the Python executable
For Windows paths in the
env
block:Use forward slashes (
/
) for better compatibilityDo not include the
.exe
extension
The
command
path must point to thepython.exe
executable inside the.venv
you createdThe
args
path must point to themain.py
file within theobsidian_mcp_server
subfolderUsing the
env
block is the most reliable way to ensure the server finds your vault pathRemember to restart the client application after modifying its JSON configuration
Common Pitfalls to Avoid:
Don't use single backslashes in Windows paths
Don't include comments in the JSON
Don't forget to escape backslashes in Windows paths
Don't mix forward and backslashes in the same path
Don't forget to properly quote all strings
Available MCP Tools
list_folders
list_notes
get_note_content
get_note_metadata
get_outgoing_links
get_backlinks
get_all_tags
search_notes_content
search_notes_metadata
search_folders
create_note
edit_note
append_to_note
update_note_metadata
delete_note
get_daily_note_path
create_daily_note
append_to_daily_note
Roadmap
For a detailed, phased implementation plan including error handling considerations, please see the ROADMAP.md file.
This project is actively developed. Here's a look at planned features:
v1.x (Near Term)
Template-Based Note Creation:
Configure a template directory (
OMCP_TEMPLATE_DIR
).Implement
create_note_from_template
tool (using template name, target path, optional metadata).Add tests for template creation.
Folder Creation:
Implement
create_folder
utility function.Implement
create_folder
MCP tool.Add tests for folder creation.
v1.y (Mid Term / Future Enhancements)
Variable substitution in templates (e.g.,
{{DATE}}
).list_templates
tool.Advanced note update tools (e.g.,
append_to_note_by_metadata
).list_vault_structure
tool for comprehensive vault hierarchy view.Comprehensive testing review and expansion.
v2.x+ (Potential Ideas / Longer Term)
Organization Tools:
move_item(source, destination)
(Initial version might not update links).rename_item(path, new_name)
(Initial version might not update links).
Content Manipulation Tools:
replace_text_in_note(path, old, new, count)
.prepend_to_note(path, content)
.append_to_section(path, heading, content)
(Requires reliable heading parsing).
Querying Tools:
get_local_graph(path)
(Combine outgoing/backlinks).search_notes_by_metadata_field(key, value)
.
Plugin Integration Tools:
Dataview Integration:
execute_dataview_query(query_type, query)
- Run Dataview queries and get structured resultssearch_by_dataview_field(field, value)
- Search notes by Dataview fields
Task Management:
query_tasks(status, due_date, tags)
- Search and filter tasks across vault
Kanban Integration:
get_kanban_data(board_path)
- Get structured kanban board data
Calendar Integration:
get_calendar_events(start_date, end_date)
- Query calendar events and tasks
Frequently Asked Questions (FAQ)
Configuration Issues
Q: My server can't find my vault. What's wrong? A: This is usually due to incorrect path configuration. Check:
The
OMCP_VAULT_PATH
in your.env
file uses forward slashes (/
) even on WindowsThe path is absolute (starts from root)
The path doesn't end with a trailing slash
The vault directory exists and is accessible
Q: Why am I getting permission errors? A: This typically happens when:
The vault path points to a restricted directory
The Python process doesn't have read/write permissions
The vault is in a cloud-synced folder (like OneDrive) that's currently syncing
Try:
Moving your vault to local directory
Running the server with elevated permissions
Checking your antivirus isn't blocking access
Client Connection Issues
Q: My AI client can't connect to the server. What should I check? A: Verify these common issues:
The server is actually running (check terminal output)
The port in your client config matches the server's port
The Python path in your client config points to the correct virtual environment
All environment variables are properly set in the client config
Q: Why do I get "Connection refused" errors? A: This usually means:
The server isn't running
The port is already in use
Firewall is blocking the connection
Try:
Check if the server is running:
netstat -ano | findstr :8001
(Windows)Try a different port by setting
OMCP_SERVER_PORT
in your.env
Temporarily disable firewall to test
Q: I get "[error] [obsidian_vault] Unexpected token 'S', "Starting O"... is not valid JSON". What's wrong? A: This error occurs when the client's JSON configuration file is malformed. Common causes:
Missing or extra commas in the JSON
Unescaped backslashes in Windows paths
Comments in the JSON (JSON doesn't support comments)
Check your client config file (e.g., claude_desktop_config.json
):
Use a JSON validator (like jsonlint.com) to check syntax
For Windows paths, escape backslashes:
"C:\\path\\to\\file"
Remove any comments (// or /* */)
Ensure all strings are properly quoted
Check that all brackets and braces are properly closed
Example of correct Windows path formatting:
Q: I get a timeout error and "Server disconnected" message. What's happening? A: This error pattern (initialization succeeds, then times out after 60 seconds) usually means:
The server is already running in another process
The port is already in use by another application
The server process is being terminated unexpectedly
Try these steps in order:
Check for running server processes:
# On Windows netstat -ano | findstr :8001 # Look for the PID and then: taskkill /F /PID <PID># On Linux/macOS lsof -i :8001 # Look for the PID and then: kill -9 <PID>Check for other applications using the port:
Close any other applications that might use port 8001
This includes other MCP servers, development servers, or any web applications
If you're not sure, try changing the port in your
.env
:OMCP_SERVER_PORT=8002
Verify server process:
Open Task Manager (Windows) or Activity Monitor (macOS)
Look for any Python processes related to the MCP server
End any suspicious processes
Check system resources:
Ensure you have enough memory and CPU available
Check if any antivirus or security software is blocking the process
Verify your Python environment has proper permissions
Reset everything:
Stop the client application
Kill any remaining server processes
Delete the
.env
file and create a new one from.env.example
Restart your computer (if other steps don't work)
Start fresh with the client application
If the issue persists after trying all these steps, please share:
The complete error log
The output of
netstat -ano | findstr :8001
(Windows) orlsof -i :8001
(Linux/macOS)Any error messages from your system's event logs
Q: The server disconnects immediately with "Server transport closed unexpectedly... process exiting early". What's wrong? A: This error means the Python server process crashed almost immediately after being launched by the client. It's not a timeout; the server script itself failed to run or stay running.
Common Causes:
Incorrect Paths in Client JSON:
command
doesn't point to the correctpython.exe
inside the.venv
.args
doesn't point to the correctobsidian_mcp_server/main.py
script.Incorrect path separators or missing backslash escapes (
\\
) on Windows.
Missing Dependencies:
Required packages from
requirements.txt
are not installed in the.venv
.The client is launching Python without properly activating the virtual environment.
Syntax Errors: A recent code change introduced a Python syntax error.
Critical Configuration/Permission Error:
Error reading the
.env
file at startup.Invalid or inaccessible
OMCP_VAULT_PATH
.Python process lacks permissions to run or access files.
Early Unhandled Exception: An error occurs during initial setup before the server starts listening.
Troubleshooting Steps:
Verify Client JSON Paths: Double-check the absolute paths for
command
andargs
in your client's JSON config. Use escaped backslashes (\\
) for Windows paths.Test Manually (Crucial Step):
Activate the virtual environment in your terminal:
# On Windows .\.venv\Scripts\activate# On Linux/macOS source .venv/bin/activateRun the server directly:
python obsidian_mcp_server/main.pyLook closely for any error messages printed directly in the terminal. This bypasses the client and often reveals the root cause (like
ImportError
,SyntaxError
,FileNotFoundError
).
Check Dependencies: With the venv activated, run
pip check
andpip install -r requirements.txt
.Validate Ensure
.env
exists, is readable, andOMCP_VAULT_PATH
is correct (use forward slashes/
).Review Recent Code Changes: Check for syntax errors or issues in recently edited Python files.
Note Operations
Q: Why can't I create/edit notes in certain folders? A: This could be due to:
Path security restrictions (trying to write outside vault)
Folder permissions
File locks from other processes
Try:
Using relative paths within your vault
Checking folder permissions
Closing other programs that might have the files open
Q: Why are my note updates not being saved? A: Common causes:
The note path is incorrect
The content format is invalid
Backup creation failed
Check:
The note path exists and is accessible
The content is valid markdown
The backup directory has write permissions
Daily Notes
Q: Why aren't my daily notes being created in the right location? A: Verify:
OMCP_DAILY_NOTE_LOCATION
is set correctly in.env
The path uses forward slashes
The target folder exists
The date format matches your vault's settings
General Troubleshooting
Q: How do I check if the server is working correctly? A: Run the test client:
This will perform a series of operations and report any issues.
Q: Where can I find error logs? A: Check:
The terminal where the server is running
The backup directory for failed operations
The system event logs for permission issues
Q: How do I reset everything to start fresh? A: Try these steps:
Stop the server
Delete the
.env
fileCreate a new
.env
from.env.example
Restart the server
Contributions Welcome!
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.
Provides an MCP server that allows AI assistants to interact with Obsidian vaults, enabling reading/writing notes, managing metadata, searching content, and working with daily 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 -349MIT 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 -58MIT License
- AsecurityAlicenseAqualityThis 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 -1177209MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.Last updated -52282ISC License