Obsidian Semantic

You use the Obsidian Semantic MCP Server to manage Obsidian operations through a compact, AI-augmented set of semantic actions. It combines powerful vault interactions, smart editing, viewing helpers, guided workflows, and essential system tasks into five cohesive operations, making it easier for AI tools to work with your Obsidian vault while conserving tokens and improving reliability.

How to use

You connect to the MCP server with a client that supports MCP connections. The server exposes five semantic operations that you invoke by choosing an operation and its action, then supplying the needed parameters. Expect context-aware hints that guide the next steps and smart recovery suggestions if something goes wrong.

Typical usage patterns include reading and editing vault files, navigating content for quick access, requesting guided workflow suggestions, and performing lightweight system inquiries. The design emphasizes semantic intent: you do not need to pick from dozens of granular tools. Instead you choose a high-level operation (vault, edit, view, workflow, system) and let the server handle the details.

How to install

Prerequisites: you should have Obsidian installed, a local REST API plugin configured in your vault, and access to Claude Desktop if you plan to run via that integration.

Install the MCP server package globally and run it using a client that supports MCP connections. Use either the global install or the direct run approach shown here.

# Install the MCP server globally
npm install -g obsidian-semantic-mcp

# Or run directly without installation
npx obsidian-semantic-mcp

Configuration and runtime setup

You will configure how the MCP server connects to Obsidian and your vault, typically via environment variables. The common pattern uses the following keys to pass API credentials, the Obsidian vault name, and the API URL.

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

Environment variables

The server automatically loads environment variables from a .env file if present. You typically provide the API key from your Local REST API plugin, and you may specify the API URL and vault name to scope the session to a particular vault.

Tools and capabilities overview

This MCP server consolidates twenty traditional tools into five semantic operations to simplify AI interaction with Obsidian and improve resilience through state tracking and smart hints.

Key benefits include a simplified interface with contextual workflow hints, token-aware state management, robust error recovery, fuzzy matching for edits, and fragment retrieval to reduce token usage when handling large files.

Notes on fragments and content handling

When reading large documents, the system can return relevant fragments instead of the entire file to save tokens. You can request fragments or the full file depending on your needs.

Starting and stopping the server

Start the MCP server using your preferred method (CLI, script, or IDE integration). When running through an adapter like Claude Desktop, ensure your configuration passes the correct API key, URL, and vault name.

Troubleshooting tips

If you encounter timeouts or missing content, verify that the Local REST API plugin is installed and accessible, and confirm that OBSIDIAN_API_KEY and OBSIDIAN_API_URL are correctly configured for your vault.

Security and access control

Keep your API key secure and restrict access to trusted environments. If you are using HTTPS, ensure certificates are correctly configured and trusted by your client.

Compatibility notes

This server is designed to work with Obsidian and the Local REST API plugin. It is intended for use with MCP clients that can communicate via the defined semantic operations.

Available tools

vault

File and folder operations with actions like list, read, create, update, delete, search, and fragments

edit

Smart content editing with actions such as window (fuzzy match), append, patch, at_line, and from_buffer

view

Content viewing and navigation with actions like window (contextual) and open_in_obsidian

workflow

Get guided suggestions to advance tasks with the suggest action

system

System operations including info, commands, and fetch_web