obsidian-mcp

Universal Agentic Knowledge Base — A CLI tool and MCP server backed by an Obsidian vault that serves as shared memory for AI coding tools.

Features

• MCP Server — Works as an MCP server for Claude Desktop, Cursor, OpenCode, and any MCP-compatible client
• CLI Tool — Full CLI interface for manual vault operations
• Project Auto-Discovery — Detects projects from CWD via git root and project-map.json
• Knowledge Management — Tasks, decisions (ADRs), learnings, sessions, brainstorms
• Full-Text Search — Powered by ripgrep
• Skill Installer — Install and manage AI skills from git repos, local files, or URLs
• Multi-Agent Coordination — Session registry for agent swarms

Installation

npm install -g @gopherine/obsidian-mcp

Or use directly with npx (no install needed):

npx @gopherine/obsidian-mcp

Or clone and build:

git clone https://github.com/gopherine/obsidian-mcp.git
cd obsidian-mcp
npm install && npm run build

Note: The default binary runs the MCP server. The CLI is available as obsidian-mcp-cli.

Quick Start

# MCP server (add to your MCP client config — see below)
npx @gopherine/obsidian-mcp

# CLI tool
npx @gopherine/obsidian-mcp-cli --help

CLI Commands

| Shorthand | Full Command | Description | |-----------|--------------|-------------| | r | read <path> | Read a vault note | | w | write <path> | Write/create a vault note | | s | search <query> | Search the vault | | c | context | Get project context | | i | init <path> | Initialize project context | | d | decide | Log an architecture decision | | t | task | Manage tasks | | t add | task add | Add a task | | t ls | task list | List tasks | | t b | task board | Show kanban board | | l | learn | Manage learnings | | l add | learn add | Capture a learning | | l ls | learn list | List learnings | | sk i | skill install | Install a skill | | sk ls | skill list | List installed skills | | sk rm | skill delete | Remove a skill |

MCP Setup

Claude Code

Add to your project's CLAUDE.md or run:

claude mcp add obsidian-mcp -- npx -y @gopherine/obsidian-mcp

Or add to ~/.claude.json:

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": ["-y", "@gopherine/obsidian-mcp"]
    }
  }
}

Set your vault path:

claude mcp add obsidian-mcp -e VAULT_PATH=~/Vaults/ai -- npx -y @gopherine/obsidian-mcp

Claude Desktop

Add to your Claude config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": ["-y", "@gopherine/obsidian-mcp"],
      "env": {
        "VAULT_PATH": "~/Vaults/ai"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": ["-y", "@gopherine/obsidian-mcp"]
    }
  }
}

OpenCode

Add to your MCP configuration:

{
  "mcpServers": {
    "obsidian-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gopherine/obsidian-mcp"]
    }
  }
}

OpenAI Codex

Add to your MCP configuration:

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": ["-y", "@gopherine/obsidian-mcp"]
    }
  }
}

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | VAULT_PATH | ~/Vaults/ai | Path to Obsidian vault | | MAX_INJECT_TOKENS | 1500 | Max tokens for context injection | | SESSION_TTL_HOURS | 2 | Session heartbeat TTL |

Vault Structure

~/Vaults/ai/
├── project-map.json           # Path → slug mappings
├── coordination/
│   ├── session-registry.json  # Active agent sessions
│   └── locks/                 # PID lockfiles
├── skills/
│   ├── installed/             # Installed skills
│   └── registry.json          # Skill metadata
└── projects/<slug>/
    ├── context.md             # Project overview
    ├── decisions/             # Architecture Decision Records
    ├── tasks/                 # Task files
    ├── learnings/             # Learning captures
    ├── sessions/              # Session notes
    ├── brainstorms/           # Brainstorm documents
    └── _archive/              # Pruned content

MCP Tools

| Tool | Description | |------|-------------| | vault_read | Read file or directory | | vault_write | Write/append/prepend content | | vault_search | Full-text search | | vault_project_context | Get project context | | vault_init | Generate draft context.md | | vault_decide | Log architecture decision | | vault_task | Manage tasks (add/list/update/board) | | vault_learn | Capture/list learnings | | vault_session | Register/heartbeat/complete sessions | | vault_skill_* | Skill installer operations | | vault_prune | Archive/delete stale content | | vault_stats | Content statistics | | vault_resume | Resume context for continuing work | | vault_deprecate | Mark items as deprecated |

Testing

# Run all tests with Vitest
npm test

# Run with coverage (target: 90%+)
npm run test:coverage

# Run specific test file
npm test src/commands/task.test.ts

# Watch mode
npm run test:watch

Tests use table-driven pattern for comprehensive coverage. All test files are *.test.ts alongside source files.

Documentation

• Contributing
• Code of Conduct
• Changelog

License

AGPL-3.0 — See LICENSE