Obsidian Semantic MCP Server

An AI-optimized MCP server for Obsidian that consolidates over 21 tools into 5 intelligent operations with contextual workflow hints.

🎉Exciting News!We've taken everything we learned from this project and created something even better! Check out the newObsidian MCP Plugin- a native Obsidian plugin that runs directly inside your vault with improved performance, simplified setup, and enhanced features. We encourage you to try it out!

This MCP server taught us valuable lessons about AI integration with Obsidian. We've applied these insights to create theObsidian MCP Plugin, which offers:

- Obsidianinstalled on your computer
- Local REST APIplugin installed in your Obsidian vault
- Claude Desktopapp

View on npm:https://www.npmjs.com/package/obsidian-semantic-mcp

- Open Obsidian Settings → Community Plugins
- Browse and search for "Local REST API"
- Install theLocal REST APIplugin by Adam Coddington
- Enable the plugin
- In the plugin settings, copy your API key (you'll need this for configuration)

{ "mcpServers": { "obsidian": { "command": "npx", "args": ["-y", "obsidian-semantic-mcp"], "env": { "OBSIDIAN_API_KEY": "your-api-key-here", "OBSIDIAN_API_URL": "https://127.0.0.1:27124", "OBSIDIAN_VAULT_NAME": "your-vault-name" } } } }

This server consolidates traditional MCP tools into an AI-optimized semantic interface that makes it easier for AI agents to understand and use Obsidian operations effectively.

- Simplified Interface: 5 semantic operations instead of 21+ individual tools
- Contextual Workflows: Intelligent hints guide AI agents to the next logical action
- State Tracking: Token-based system prevents invalid operations
- Error Recovery: Smart recovery hints when operations fail
- Fuzzy Matching: Resilient text editing that handles minor variations
- Fragment Retrieval: Automatically returns relevant sections from large files to conserve tokens

Traditional MCP servers expose many granular tools (20+), which can overwhelm AI agents and lead to inefficient tool selection. Our semantic approach:

- Consolidates 20 tools into 5 semantic operationsbased on intent
- Provides contextual workflow hintsto guide next actions
- Tracks state with tokens(inspired by Petri nets) to prevent nonsensical suggestions
- Offers recovery hintswhen operations fail

- Actions:list,read,create,update,delete,search,fragments

- Actions:window(fuzzy match),append,patch,at_line,from_buffer

- Actions:window(with context),open_in_obsidian

- Actions:info,commands,fetch_web
- Note:fetch_webfetches and converts web content to markdown (uses onlyurlparameter)

Instead of choosing betweenget_vault_file,get_active_file,read_file_content, etc., you simply use:

{ "operation": "vault", "action": "read", "params": { "path": "daily-notes/2024-01-15.md" } }

The response includes intelligent workflow hints:

{ "result": { / file content / }, "workflow": { "message": "Read file: daily-notes/2024-01-15.md", "suggested_next": [ { "description": "Edit this file", "command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)", "reason": "Make changes to content" }, { "description": "Follow linked notes", "command": "vault(action='read', path='{linked_file}')", "reason": "Explore connected knowledge" } ] } }

The system tracks context tokens to provide relevant suggestions:

- After reading a file with[[links]], it suggests following them
- After a failed edit, it offers buffer recovery options
- After searching, it suggests refining or reading results

Thewindowedit action automatically buffers your new content before attempting the edit. If the edit fails or you want to refine it, you can retrieve from buffer:

{ "operation": "edit", "action": "from_buffer", "params": { "path": "notes/meeting.md" } }

The semantic editor uses fuzzy matching to find and replace content:

{ "operation": "edit", "action": "window", "params": { "path": "daily/2024-01-15.md", "oldText": "meting notes", // typo will be fuzzy matched "newText": "meeting notes", "fuzzyThreshold": 0.8 } }

{ "operation": "edit", "action": "patch", "params": { "path": "projects/todo.md", "operation": "append", "targetType": "heading", "target": "## In Progress", "content": "- [ ] New task" } }

The system automatically uses intelligent fragment retrieval when reading files, significantly reducing token consumption while maintaining relevance:

{ "operation": "vault", "action": "read", "params": { "path": "large-document.md" } }

Returns relevant fragments instead of the entire file:

{ "result": { "content": [ { "id": "file:large-document.md:frag0", "content": "Most relevant section...", "score": 0.95, "lineStart": 145, "lineEnd": 167 } ], "fragmentMetadata": { "totalFragments": 5, "strategy": "adaptive", "originalContentLength": 135662 } } }

- adaptive- TF-IDF keyword matching (default for short queries)
- proximity- Finds fragments where query terms appear close together
- semantic- Chunks documents into meaningful sections

You can explicitly search for fragments across your vault:

{ "operation": "vault", "action": "fragments", "params": { "query": "project roadmap timeline", "maxFragments": 10, "strategy": "proximity" } }

To retrieve the full file (when needed), use:

{ "operation": "vault", "action": "read", "params": { "path": "document.md", "returnFullFile": true } }

- Create today's note → 2. Add template → 3. Link yesterday's note
- Search topic → 2. Read results → 3. Create synthesis note → 4. Link sources
- Find all mentions → 2. Update links → 3. Rename/merge notes

The semantic workflow hints are defined insrc/config/workflows.jsonand can be customized for your workflow preferences.

The fragment retrieval system automatically activates when reading files to conserve tokens. You can control this behavior:

- Default behavior: Returns up to 5 relevant fragments when reading files
- Full file access: UsereturnFullFile: trueparameter to get complete content
- Strategy selection: The system auto-selects based on query length, or you can specify:

- adaptivefor keyword matching (1-2 word queries)
- proximityfor finding related terms together (3-5 word queries)
- semanticfor conceptual chunking (longer queries)

When operations fail, the semantic interface provides intelligent recovery hints:

{ "error": { "code": "FILE_NOT_FOUND", "message": "File not found: daily/2024-01-15.md", "recovery_hints": [ { "description": "Create this file", "command": "vault(action='create', path='daily/2024-01-15.md')" }, { "description": "Search for similar files", "command": "vault(action='search', query='2024-01-15')" } ] } }

The server automatically loads environment variables from a.envfile if present. Variables can be set in order of precedence:
- Existing environment variables (highest priority)
- .envfile in current working directory
- .envfile in the server directory

- OBSIDIAN_API_KEY- Your API key from the Local REST API plugin

- OBSIDIAN_API_URL- API URL (default:https://localhost:27124)

OBSIDIAN_API_KEY=your-api-key-here OBSIDIAN_API_URL=http://127.0.0.1:27123 OBSIDIAN_VAULT_NAME=MyVault

{ "operation": "append", "targetType": "heading", "target": "Daily Notes::Today", "content": "- New task added" }

# Clone and install git clone https://github.com/aaronsb/obsidian-semantic-mcp.git cd obsidian-semantic-mcp npm install # Development mode npm run dev # Testing npm test # Run all tests npm run test:coverage # With coverage report # Build npm run build # Build the server npm run build:full # Test + Build # Start npm start # Start the server

npm test # Run all tests npm test semantic-router # Test routing logic npm test semantic-tools # Test integration

Manage and share personal knowledge, daily notes, and reusable prompts using GitHub Gists.