Obsidian
About
A server for interacting with your Obsidian vault.
Details
- Author
- rwb3n
- Categories
- Productivity, Other, Knowledge Base
Jump to
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.envfile as described in the Configuration section.
- Activate Virtual Environment:
# If not already active .venv\Scripts\Activate.ps1
(.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 pressCtrl+Cto stop it when finished testing.
Remember:If you intend to use this server with Claude Desktop or a similar launcher, you shouldnotrun 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.jsonon macOS/Linux, find the equivalent path on Windows underAppData).
- JSON filesdo notsupport 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](#contributions-welcome)jsonlint.com) to check your syntax
Here's an example entry to add under themcpServerskey in the client's JSON configuration:
{ "mcpServers": { "obsidian_vault": { "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe", "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"], "env": { "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault", "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily" } } } }
- Replace the paths with theabsolute pathsrelevant to your system
- For Windows paths in thecommandandargsfields:
- Use double backslashes (\\) for path separators
- Include the.exeextension for the Python executable
- Use forward slashes (/) for better compatibility
- Do not include the.exeextension
- 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
- 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
For a detailed, phased implementation plan including error handling considerations, please see theROADMAP.mdfile.
This project is actively developed. Here's a look at planned features:
- Template-Based Note Creation:
- Configure a template directory (OMCP_TEMPLATE_DIR).
- Implementcreate_note_from_templatetool (using template name, target path, optional metadata).
- Add tests for template creation.
- Implementcreate_folderutility function.
- Implementcreate_folderMCP tool.
- Add tests for folder creation.
- Variable substitution in templates (e.g.,{{DATE}}).
- list_templatestool.
- Advanced note update tools (e.g.,append_to_note_by_metadata).
- list_vault_structuretool for comprehensive vault hierarchy view.
- Comprehensive testing review and expansion.
- Organization Tools:
- move_item(source, destination)(Initial version might not update links).
- rename_item(path, new_name)(Initial version might not update links).
- replace_text_in_note(path, old, new, count).
- prepend_to_note(path, content).
- append_to_section(path, heading, content)(Requires reliable heading parsing).
- get_local_graph(path)(Combine outgoing/backlinks).
- search_notes_by_metadata_field(key, value).
- Dataview Integration:
- execute_dataview_query(query_type, query)- Run Dataview queries and get structured results
- search_by_dataview_field(field, value)- Search notes by Dataview fields
- query_tasks(status, due_date, tags)- Search and filter tasks across vault
- get_kanban_data(board_path)- Get structured kanban board data
- get_calendar_events(start_date, end_date)- Query calendar events and tasks
Q: My server can't find my vault. What's wrong?A: This is usually due to incorrect path configuration. Check:
- TheOMCP_VAULT_PATHin your.envfile uses forward slashes (/) even on Windows
- The 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
- Moving your vault to local directory
- Running the server with elevated permissions
- Checking your antivirus isn't blocking access
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
- Check if the server is running:netstat -ano | findstr :8001(Windows)
- Try a different port by settingOMCP_SERVER_PORTin 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 (likejsonlint.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:
{ "mcpServers": { "obsidian_vault": { "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe", "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"] } } }
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
# 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
- Open Task Manager (Windows) or Activity Monitor (macOS)
- Look for any Python processes related to the MCP server
- End any suspicious processes
- 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
- Stop the client application
- Kill any remaining server processes
- Delete the.envfile 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 ofnetstat -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.
- Incorrect Paths in Client JSON:
- commanddoesn't point to the correctpython.exeinsidethe.venv.
- argsdoesn't point to the correctobsidian_mcp_server/main.pyscript.
- Incorrect path separators or missing backslash escapes (\\) on Windows.
- Required packages fromrequirements.txtare not installed in the.venv.
- The client is launching Python without properly activating the virtual environment.
- Error reading the.envfile at startup.
- Invalid or inaccessibleOMCP_VAULT_PATH.
- Python process lacks permissions to run or access files.
- Verify Client JSON Paths:Double-check the absolute paths forcommandandargsin 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/activate
Q: Why can't I create/edit notes in certain folders?A: This could be due to:
This project provides a Model Context Protocol (MCP) server that exposes tools for interacting with an Obsidian vault.
- Features
- Installation
- Configuration
- Running Manually (for Testing/Debugging)
- Client Configuration (Example: Claude Desktop)
- Available MCP Tools
- Roadmap
- Frequently Asked Questions (FAQ)
- Contributions Welcome!
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
-
Clone the repository(if you haven't already):
# git clone <repository-url> # cd OMCP
Create a Python virtual environment(recommended to avoid dependency conflicts):
- On Windows PowerShell:
.venv\Scripts\Activate.ps1
(Your terminal prompt should now show(.venv)at the beginning)
Install the packageand its dependencies:
This server is configured using environment variables, which can be conveniently managed using a.envfile in the project root.
# From the project root directory (OMCP/) cp .env.example .env
(On Windows, you might usecopy .env.example .env)
Edit the.envfile:Open the newly created.envfile in a text editor.
SetOMCP_VAULT_PATH:This is the onlyrequiredvariable. Update it with theabsolute pathto your Obsidian vault. Use forward slashes (/) for paths, even on Windows.
OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"
Review Optional Settings:Adjust the otherOMCP_variables for daily notes, server port, or backup directory if needed. Read the comments in the file for explanations.
(Alternatively, instead of using a.envfile, you can set these as actual system environment variables. The server will prioritize system environment variables over the.envfile if both are set.)
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.envfile as described in the Configuration section.
- Activate Virtual Environment:
# If not already active .venv\Scripts\Activate.ps1
(.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 pressCtrl+Cto stop it when finished testing.
Remember:If you intend to use this server with Claude Desktop or a similar launcher, you shouldnotrun 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.jsonon macOS/Linux, find the equivalent path on Windows underAppData).
- JSON filesdo notsupport comments (remove any//or/ /comments)
- All strings must be properly quoted with double quotes (")
- Windows paths must use escaped backslashes (\\)
- Use a JSON validator (likejsonlint.com) to check your syntax
Here's an example entry to add under themcpServerskey in the client's JSON configuration:
{ "mcpServers": { "obsidian_vault": { "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe", "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"], "env": { "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault", "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily" } } } }
- Replace the paths with theabsolute pathsrelevant to your system
- For Windows paths in thecommandandargsfields:
- Use double backslashes (\\) for path separators
- Include the.exeextension for the Python executable
- Use forward slashes (/) for better compatibility
- Do not include the.exeextension
- 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
- 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
For a detailed, phased implementation plan including error handling considerations, please see theROADMAP.mdfile.
This project is actively developed. Here's a look at planned features:
- Template-Based Note Creation:
- Configure a template directory (OMCP_TEMPLATE_DIR).
- Implementcreate_note_from_templatetool (using template name, target path, optional metadata).
- Add tests for template creation.
- Implementcreate_folderutility function.
- Implementcreate_folderMCP tool.
- Add tests for folder creation.
- Variable substitution in templates (e.g.,{{DATE}}).
- list_templatestool.
- Advanced note update tools (e.g.,append_to_note_by_metadata).
- list_vault_structuretool for comprehensive vault hierarchy view.
- Comprehensive testing review and expansion.
- Organization Tools:
- move_item(source, destination)(Initial version might not update links).
- rename_item(path, new_name)(Initial version might not update links).
- replace_text_in_note(path, old, new, count).
- prepend_to_note(path, content).
- append_to_section(path, heading, content)(Requires reliable heading parsing).
- get_local_graph(path)(Combine outgoing/backlinks).
- search_notes_by_metadata_field(key, value).
- Dataview Integration:
- execute_dataview_query(query_type, query)- Run Dataview queries and get structured results
- search_by_dataview_field(field, value)- Search notes by Dataview fields
- query_tasks(status, due_date, tags)- Search and filter tasks across vault
- get_kanban_data(board_path)- Get structured kanban board data
- get_calendar_events(start_date, end_date)- Query calendar events and tasks
Q: My server can't find my vault. What's wrong?A: This is usually due to incorrect path configuration. Check:
- TheOMCP_VAULT_PATHin your.envfile uses forward slashes (/) even on Windows
- The 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
- Moving your vault to local directory
- Running the server with elevated permissions
- Checking your antivirus isn't blocking access
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
- Check if the server is running:netstat -ano | findstr :8001(Windows)
- Try a different port by settingOMCP_SERVER_PORTin 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 (likejsonlint.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:
{ "mcpServers": { "obsidian_vault": { "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe", "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"] } } }
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
# 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
- Open Task Manager (Windows) or Activity Monitor (macOS)
- Look for any Python processes related to the MCP server
- End any suspicious processes
- 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
- Stop the client application
- Kill any remaining server processes
- Delete the.envfile 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 ofnetstat -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.
- Incorrect Paths in Client JSON:
- commanddoesn't point to the correctpython.exeinsidethe.venv.
- argsdoesn't point to the correctobsidian_mcp_server/main.pyscript.
- Incorrect path separators or missing backslash escapes (\\) on Windows.
- Required packages fromrequirements.txtare not installed in the.venv.
- The client is launching Python without properly activating the virtual environment.
- Error reading the.envfile at startup.
- Invalid or inaccessibleOMCP_VAULT_PATH.
- Python process lacks permissions to run or access files.
- Verify Client JSON Paths:Double-check the absolute paths forcommandandargsin 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/activate
Q: Why can't I create/edit notes in certain folders?A: This could be due to:
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
