obsidian-api-mcp

MCP server for Obsidian with full Canvas support.

Prerequisites

Required: Install the Local REST API plugin in Obsidian.

Install via BRAT:

1. Install BRAT from Obsidian Community Plugins
2. Add Beta plugin: ArtiPyHeart/obsidian-local-rest-api
3. Enable the plugin and copy your API key from settings

Features

• Async architecture - Uses httpx.AsyncClient for non-blocking HTTP requests
• Coarse-grained tools - 6 tools instead of 16+ to reduce context overhead
• Full Canvas support - Read, create, and modify Canvas nodes and edges
• Canvas search - Search results include Canvas text nodes with metadata

Installation

From PyPI (recommended)

# Using uvx (recommended)
uvx obsidian-api-mcp

# Or install with pip
pip install obsidian-api-mcp

From source

git clone https://github.com/ArtiPyHeart/obsidian-local-rest-api.git
cd obsidian-local-rest-api/mcp/obsidian-mcp
uv pip install -e .

Configuration

Set environment variables (or use a .env file):

Variable	Description	Default
OBSIDIAN_API_KEY	API key from Local REST API plugin	(required)
OBSIDIAN_HOST	Obsidian host	127.0.0.1
OBSIDIAN_PORT	Obsidian port	27123
OBSIDIAN_PROTOCOL	Protocol (http or https)	http
OBSIDIAN_VERIFY_SSL	Verify SSL certificates	false

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian-api-mcp": {
      "command": "uvx",
      "args": ["obsidian-api-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27123",
        "OBSIDIAN_PROTOCOL": "http"
      }
    }
  }
}

Tools

1. obsidian_files - File Operations

Unified file operations for the Obsidian vault.

Operations:

• list - List files in a directory (use path="" for root)
• get - Get content of a single file
• batch_get - Get contents of multiple files concatenated
• put - Create or overwrite a file
• append - Append content to a file
• delete - Delete a file

{
  "operation": "get",
  "path": "notes/example.md"
}

2. obsidian_patch - Content Insertion

Insert content relative to a heading, block reference, or frontmatter field.

Target types:

• heading - Target a heading path (use :: as delimiter for nested headings)
• block - Target a block reference (without ^ prefix)
• frontmatter - Target a frontmatter field name

Operations: append, prepend, replace

Heading example (note: use full heading path):

{
  "filepath": "note.md",
  "target_type": "heading",
  "target": "Main Title::Tasks",
  "operation": "append",
  "content": "\n- [ ] New task"
}

Frontmatter example:

{
  "filepath": "note.md",
  "target_type": "frontmatter",
  "target": "status",
  "operation": "replace",
  "content": "published"
}

Block reference example:

{
  "filepath": "note.md",
  "target_type": "block",
  "target": "my-block-id",
  "operation": "append",
  "content": "\nAdditional content"
}

3. obsidian_search - Search

Search for documents in the vault.

Query types:

• simple - Text search across all files (including Canvas text nodes)
• complex - JsonLogic query for advanced filtering

{
  "query_type": "simple",
  "query": "project ideas",
  "context_length": 100
}

{
  "query_type": "complex",
  "query": {"glob": ["*.md", {"var": "path"}]}
}

4. obsidian_periodic - Periodic Notes

Operations for periodic notes and recent changes.

Note: Requires Periodic Notes plugin for get/recent operations, and Dataview plugin for changes operation.

Operations:

• config - Get periodic notes configuration (folders, formats, enabled status)
• get - Get current periodic note (daily/weekly/monthly/quarterly/yearly)
• recent - Get most recent periodic notes of a type
• changes - Get recently modified files (requires Dataview plugin)

Get configuration:

{
  "operation": "config"
}

Get current periodic note:

{
  "operation": "get",
  "period": "daily",
  "include_metadata": true
}

Get recent periodic notes:

{
  "operation": "recent",
  "period": "daily",
  "limit": 5,
  "include_content": true
}

Get recently changed files:

{
  "operation": "changes",
  "limit": 10,
  "days": 30
}

5. obsidian_canvas_read - Read Canvas

Get Canvas file structure and metadata.

{
  "filepath": "my-canvas.canvas",
  "include_metadata": true
}

6. obsidian_canvas_write - Modify Canvas

Add, update, or delete Canvas nodes and edges.

Target types:

• node / edge - Single operations (requires operation)
• nodes / edges - Batch operations

Node types: text, file, link, group

Single node add:

{
  "filepath": "my-canvas.canvas",
  "target_type": "node",
  "operation": "add",
  "id": "node1",
  "node_type": "text",
  "x": 0,
  "y": 0,
  "width": 200,
  "height": 100,
  "text": "Hello World"
}

Single node update:

{
  "filepath": "my-canvas.canvas",
  "target_type": "node",
  "operation": "update",
  "id": "node1",
  "text": "Updated text"
}

Single edge add:

{
  "filepath": "my-canvas.canvas",
  "target_type": "edge",
  "operation": "add",
  "id": "edge1",
  "fromNode": "node1",
  "toNode": "node2",
  "fromSide": "right",
  "toSide": "left"
}

Batch operations:

{
  "filepath": "my-canvas.canvas",
  "target_type": "nodes",
  "add": [
    {"id": "n1", "type": "text", "x": 0, "y": 0, "width": 200, "height": 100, "text": "Node 1"},
    {"id": "n2", "type": "text", "x": 300, "y": 0, "width": 200, "height": 100, "text": "Node 2"}
  ],
  "update": {
    "existing_node_id": {"text": "Updated content"}
  },
  "delete": ["old_node_id"]
}

Requirements

• Python 3.11+
• Obsidian with Local REST API plugin installed

License

MIT