MCP 服务器

Obsidian MCP Server

Enables AI assistants to search, read, and append content to notes in an Obsidian vault via the MCP protocol.

README

Obsidian MCP Server Plugin

Project Overview

This is an Obsidian plugin that functions as an MCP (Model Context Protocol) server, enabling Claude Desktop and other AI assistants to interact directly with an Obsidian vault. It provides a bridge between the MCP protocol (used by Claude Desktop) and the Obsidian API.

Author: Bas van Laarhoven / Sensei Bas License: MIT Version: 1.0.0

Architecture

High-Level Design

Claude Desktop (stdio)
    ↓
stdio-bridge.js (converts stdio ↔ HTTP)
    ↓
MCP Server (HTTP on localhost:3000)
    ↓
Obsidian API (vault access)

Why HTTP Instead of stdio?

Obsidian runs in Electron, which doesn't have direct stdio access. This plugin runs an HTTP server locally (localhost:3000) and uses a stdio bridge (stdio-bridge.js) to convert between:

Claude Desktop's stdio-based MCP protocol
This plugin's HTTP-based implementation

This architecture is security-conscious: the HTTP server only listens on localhost, preventing external network access.

Core Components

1. MCP Server (`src/mcp-server.ts`)

The main server class that:

Runs an HTTP server on port 3000 (localhost only)
Implements MCP protocol over JSON-RPC 2.0
Handles three core MCP methods:
- initialize - Protocol handshake
- tools/list - Returns available tools
- tools/call - Executes a tool

Key Implementation Details:

Uses Electron's built-in http module (not Node's)
CORS enabled for localhost
All requests are POST (OPTIONS for CORS preflight)
Notifications (methods starting with notifications/) are acknowledged but not processed

2. Available Tools

The plugin provides four tools for vault interaction:

`search_notes`

Location: src/tools/search-notes.ts Purpose: Search vault notes by query text Parameters:

query (required): Search text (searches titles and content)
folder (optional): Filter by folder path
tag (optional): Filter by tag (without #)
limit (optional): Max results (default: 10)

Returns: JSON array of matching notes with snippets

`get_note`

Location: src/tools/get-note.ts Purpose: Read a specific note's full content and metadata Parameters:

path (required): Vault path to note

Returns: Note content, metadata, frontmatter, tags, links

Important: Use search_notes first to find the correct path, then use get_note to read the full content.

`get_related_notes`

Location: src/tools/get-related-notes.ts Purpose: Find notes related to a specific note Parameters:

path (required): Vault path to note

Returns:

Outgoing links (notes this note links to)
Incoming links/backlinks (notes that link to this note)

Note: Returns only paths - use get_note to read full content of related notes.

`append_to_note`

Location: src/tools/append-to-note.ts Purpose: Append content to the end of an existing note Parameters:

path (required): Vault path to note
content (required): Markdown content to append

Returns: Success message

Use Cases: Adding new information, logging, extending notes without replacing content

3. Plugin Entry Point (`main.ts`)

The main Obsidian plugin class that:

Loads/unloads the plugin
Starts/stops the MCP server
Integrates with Obsidian's plugin system

4. stdio Bridge (`stdio-bridge.js`)

Standalone Node.js script that:

Reads JSON-RPC from stdin (from Claude Desktop)
Forwards to HTTP server (this plugin)
Sends HTTP responses back to stdout
Handles initialization and tool calls

Development Guide

Build Commands

npm install          # Install dependencies
npm run dev          # Watch mode (rebuilds on changes)
npm run build        # Production build

Project Structure

.
├── src/
│   ├── mcp-server.ts          # Main MCP server implementation
│   ├── types.ts               # TypeScript types
│   └── tools/
│       ├── search-notes.ts    # Search functionality
│       ├── get-note.ts        # Note reading
│       ├── get-related-notes.ts  # Link traversal
│       └── append-to-note.ts  # Note appending
├── main.ts                    # Obsidian plugin entry point
├── stdio-bridge.js            # Claude Desktop bridge
├── manifest.json              # Plugin manifest
└── package.json               # Dependencies

Key Dependencies

obsidian - Obsidian API types
esbuild - Build tool
typescript - Language
Built-in Node.js http module (via Electron)

Testing

node test-connection.js  # Test HTTP server directly
node test-mcp.js        # Test MCP protocol

Protocol Details

MCP (Model Context Protocol)

This plugin implements MCP 2024-11-05 protocol version over JSON-RPC 2.0.

Supported Methods:

initialize - Handshake, returns capabilities
tools/list - Returns tool definitions with JSON schemas
tools/call - Executes a tool with arguments

Tool Response Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool result as string"
      }
    ]
  }
}

Error Handling

Standard JSON-RPC error codes:

-32601 - Method not found
-32603 - Internal error / tool execution failed

Configuration

Claude Desktop Setup

Windows:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\Vault\\.obsidian\\plugins\\mcp-server\\stdio-bridge.js"
      ]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": [
        "/path/to/vault/.obsidian/plugins/mcp-server/stdio-bridge.js"
      ]
    }
  }
}