Obsidian Semantic MCP Server

Obsidian Semantic MCP Server

A semantic, AI-optimized MCP server for Obsidian that consolidates 21+ tools into 5 intelligent operations with contextual workflow hints.

Quick Start

1. Install in Obsidian:
   • Install the Local REST API plugin
   • Enable it and copy the API key from settings
2. Configure Claude Desktop:Add to your Claude Desktop config:
   { "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" } } } }

Features

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.

Key Benefits

• 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

Why Semantic Operations?

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

• Consolidates 21 tools into 5 semantic operations based on intent
• Provides contextual workflow hints to guide next actions
• Tracks state with tokens (inspired by Petri nets) to prevent nonsensical suggestions
• Offers recovery hints when operations fail

The 5 Semantic Operations

1. vault - File and folder operations
   • Actions: list, read, create, update, delete, search
2. edit - Smart content editing
   • Actions: window (fuzzy match), append, patch, at_line, from_buffer
3. view - Content viewing and navigation
   • Actions: window (with context), open_in_obsidian
4. workflow - Get guided suggestions
   • Actions: suggest
5. system - System operations
   • Actions: info, commands, fetch_web

Example Usage

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

The response includes intelligent workflow hints:

State-Aware Suggestions

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

Advanced Features

Content Buffering

When edits fail (e.g., text not found), content is automatically buffered and can be recovered:

Fuzzy Window Editing

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

Smart PATCH Operations

Target specific document structures:

Workflow Examples

Daily Note Workflow

1. Create today's note → 2. Add template → 3. Link yesterday's note

Research Workflow

1. Search topic → 2. Read results → 3. Create synthesis note → 4. Link sources

Refactoring Workflow

1. Find all mentions → 2. Update links → 3. Rename/merge notes

Configuration

The semantic workflow hints are defined in src/config/workflows.json and can be customized for your workflow preferences.

Error Recovery

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

Environment Variables

• OBSIDIAN_API_KEY (required) - Your API key from the Local REST API plugin
• OBSIDIAN_API_URL (optional) - API URL (default: https://localhost:27124)
  • Supports both HTTP (port 27123) and HTTPS (port 27124)
  • HTTPS uses self-signed certificates which are automatically accepted
• OBSIDIAN_VAULT_NAME (optional) - Vault name for context

PATCH Operations

The PATCH operations (patch_active_file and patch_vault_file) allow sophisticated content manipulation:

• Target Types:
  • heading: Target content under specific headings using paths like "Heading 1:"
  • block: Target specific block references
  • frontmatter: Target frontmatter fields
• Operations:
  • append: Add content after the target
  • prepend: Add content before the target
  • replace: Replace the target content

Example: Append content under a specific heading:

Development

Architecture

The semantic system consists of:

• Semantic Router (src/semantic/router.ts) - Routes operations to handlers
• State Tokens (src/semantic/state-tokens.ts) - Tracks context state
• Workflow Config (src/config/workflows.json) - Defines hints and suggestions
• Classic Tools (src/tools/) - Original tool implementations

Testing

The project includes comprehensive Jest tests for the semantic system:

Known Issues

• Search functionality: The search_vault_simple tool may hang or timeout due to a known issue in the Obsidian Local REST API plugin. As a workaround, use the file listing and reading tools to navigate your vault.

Contributing

Contributions are welcome! Areas of interest:

• Additional workflow patterns in workflows.json
• New semantic operations
• Enhanced state tracking
• Integration with Obsidian plugins

License

MIT