Obsidian Semantic MCP Server

🎉 Exciting News! We've taken everything we learned from this project and created something even better! Check out the new Obsidian 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!

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

---

🚀 Try Our New Native Plugin!

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

• Native Integration: Runs directly inside Obsidian (no external dependencies!)
• Better Performance: Direct vault access without REST API overhead
• Easier Setup: Install like any Obsidian plugin - no API keys or external servers
• Enhanced Features: Full access to Obsidian's internal APIs and search capabilities
• Improved Reliability: No more connection issues or timeouts

👉 Get the Obsidian MCP Plugin

---

Prerequisites

• Obsidian installed on your computer
• Local REST API plugin installed in your Obsidian vault
• Claude Desktop app

Installation

npm install -g obsidian-semantic-mcp

Or use directly with npx (recommended):

npx obsidian-semantic-mcp

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

Quick Start

1. Install the Obsidian Plugin:

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

2. Configure Claude Desktop:

   The npx command is automatically used in the Claude Desktop configuration. Add this to your Claude Desktop config (usually found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "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
• Fragment Retrieval: Automatically returns relevant sections from large files to conserve tokens

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 20 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, fragments

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
   • Note: fetch_web fetches and converts web content to markdown (uses only url parameter)

Example Usage

Instead of choosing between get_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"
      }
    ]
  }
}

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

The window edit 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"
  }
}

Fuzzy Window Editing

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
  }
}

Smart PATCH Operations

Target specific document structures:

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

Fragment Retrieval for Large Documents

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
    }
  }
}

Fragment Search Strategies:

• 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
  }
}

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.

Fragment Retrieval Configuration

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: Use returnFullFile: true parameter to get complete content
• Strategy selection: The system auto-selects based on query length, or you can specify:
  • adaptive for keyword matching (1-2 word queries)
  • proximity for finding related terms together (3-5 word queries)
  • semantic for conceptual chunking (longer queries)

Error Recovery

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')"
      }
    ]
  }
}

Environment Variables

The server automatically loads environment variables from a .env file if present. Variables can be set in order of precedence:

1. Existing environment variables (highest priority)
2. .env file in current working directory
3. .env file in the server directory

Required variables:

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

Optional variables:

• OBSIDIAN_API_URL - 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 - Vault name for context

Example .env file:

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

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::Subheading"
  • 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:

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

Development

# 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

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
• Core Utilities (src/utils/) - Shared functionality like file reading and fuzzy matching

Testing

The project includes comprehensive Jest tests for the semantic system:

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

Known Issues

• Search functionality: The search operation may occasionally timeout on large vaults due to API limitations in the Obsidian Local REST API plugin.

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