Kioku — MCP Server for Obsidian

Kioku (記憶) means "memory" in Japanese.

Current version: 2.3.0 · Documentation Website · View releases

Kioku is an MCP (Model Context Protocol) server that lets AI agents like Claude Code and Antigravity CLI read, search, write, and organize your Obsidian vault natively, fast, and privately — with 117 MCP tools across 18 classes and 22 plugin bridge commands.

Capabilities

• Hybrid search — full-text + semantic (Ollama embeddings) + RRF

• Read/write notes, frontmatter, and metadata

• Tag management and taxonomic organization

• Wikilink navigation — backlinks, outgoing links, knowledge graph

• Task management — native checkboxes with filters by tag, date, due date

• Zettelkasten — atomic note creation, MOCs, templates, literature notes

• CSS Theming — snippets and full themes from the agent

• Assets — Excalidraw, images, orphaned files

• Obsidian bridge — open notes, run commands, query status (optional)

• On-demand startup — consumes no resources when not in use

• Dual transport — stdio (v1, local) and HTTP-SSE (v2, multiple agents/VM)

Related MCP server: Grove

Architecture

AI Agent (Claude Code / agy)
    │
    ├── stdio (v1 — local, on-demand)
    └── HTTP-SSE (v2 — VM, multiple agents)
    │
    ▼
Kioku.Mcp.Server (C# .NET 10)
    ├── 18 Tool Classes (117 MCP tools)
    ├── Services: VaultIndex · Embedding(Ollama) · HybridSearch
    │            TaskService · ObsidianBridge · Persistence
    └── Middleware: ApiKeyMiddleware
    │
    │ WebSocket (optional, only if Obsidian is open)
    ▼
Obsidian Plugin (TypeScript) — WebSocket Server :7765
    │
    ▼
Obsidian App

Quick Start (Local Use)

Requirements

• .NET 10 SDK

• Obsidian installed with your vault of notes

• Ollama (optional, required for semantic search with nomic-embed-text)

1. Building the Server

For best performance, it's recommended to build Kioku as a single self-contained executable. This way you won't depend on running it through the dotnet SDK.

Run the command matching your operating system from the project root:

• Linux:

  dotnet publish src/Kioku.Mcp.Server/Kioku.Mcp.Server.csproj -c Release -r linux-x64 --self-contained -p:PublishSingleFile=true

• Windows (PowerShell):

  dotnet publish src/Kioku.Mcp.Server/Kioku.Mcp.Server.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true

• macOS (Intel):

  dotnet publish src/Kioku.Mcp.Server/Kioku.Mcp.Server.csproj -c Release -r osx-x64 --self-contained -p:PublishSingleFile=true

• macOS (Apple Silicon):

  dotnet publish src/Kioku.Mcp.Server/Kioku.Mcp.Server.csproj -c Release -r osx-arm64 --self-contained -p:PublishSingleFile=true

This will generate the executable binary Kioku.Mcp.Server (or Kioku.Mcp.Server.exe on Windows) in the directory: src/Kioku.Mcp.Server/bin/Release/net10.0/<runtime>/publish/

2. Registering with MCP Clients

Quick install (recommended)

For Claude Code, Codex CLI, OpenCode, and Antigravity CLI/IDE, skip the manual JSON/TOML editing below and use the one-command installer. It checks for the kioku binary (offering to run dotnet tool install -g kioku-mcp-server if it's missing) and registers the server using each client's own mechanism:

# Claude Code — installs a plugin bundling the server + the kioku-vault skill
claude plugin marketplace add sandovaldavid/kioku && claude plugin install kioku@kioku

# Codex CLI
./scripts/add-to-client.sh codex --vault /path/to/your/vault

# OpenCode
./scripts/add-to-client.sh opencode --vault /path/to/your/vault

# Antigravity CLI/IDE
./scripts/add-to-client.sh antigravity --vault /path/to/your/vault

See integrations/README.md for what each of these installs, and ./scripts/add-to-client.sh --help for all flags (--scope, --workspace, --dry-run, ...).

Manual configuration (all clients, or as a fallback)

Build the server (step 1) and then add Kioku to your favorite MCP client:

OpenCode

File: ~/.config/opencode/opencode.jsonc or ./opencode.jsonc (project)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kioku": {
      "type": "local",
      "command": ["<PATH_TO_BINARY>"],
      "environment": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      },
      "enabled": true
    }
  }
}

Claude Code

File: .mcp.json (project root) or ~/.claude.json (global)

{
  "mcpServers": {
    "kioku": {
      "type": "stdio",
      "command": "<PATH_TO_BINARY>",
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Claude Desktop

File:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

VS Code

File: .vscode/mcp.json (workspace)

{
  "servers": {
    "kioku": {
      "type": "stdio",
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Cursor

File: .cursor/mcp.json (project root)

{
  "mcpServers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Zed

File: .zed/settings.json (project) or ~/.config/zed/settings.json (global)

{
  "context_servers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.)

File:

• macOS: ~/Library/Application Support/JetBrains/AIAssistant/mcp.json

• Windows: %APPDATA%\JetBrains\AIAssistant\mcp.json

• Linux: ~/.config/JetBrains/AIAssistant/mcp.json

Or from Settings → Tools → AI Assistant → MCP.

{
  "mcpServers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Warp

Graphical configuration from Warp Settings → MCP Servers. Alternatively, in the local agent's configuration file:

{
  "mcpServers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

GitHub Copilot CLI

File: .mcp.json (project root) or .vscode/mcp.json.

{
  "mcpServers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Codex CLI (OpenAI)

File: config.toml (project root or ~/.codex/)

[mcp_servers.kioku]
command = "<PATH_TO_BINARY>"
args = []
env = { KIOKU_VAULT_PATH = "/path/to/your/vault" }

Antigravity CLI and IDE

File: .antigravity/mcp.json (project root)

{
  "mcpServers": {
    "kioku": {
      "command": "<PATH_TO_BINARY>",
      "args": [],
      "env": {
        "KIOKU_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

3. Installing the Obsidian Plugin (Optional)

To install the plugin locally in your Obsidian vault:

1. Install dependencies and build the plugin: From the project root, run:

   pnpm install
   pnpm build:plugin

   This will generate the main.js, manifest.json, and styles.css files in the src/obsidian-kioku-mcp/ folder.

2. Copy the files to your vault: Create a folder named kioku inside your Obsidian vault's hidden plugins folder (.obsidian/plugins/):

   # Create the plugin directory
   mkdir -p /path/to/your/vault/.obsidian/plugins/kioku
   
   # Copy the built files
   cp src/obsidian-kioku-mcp/{main.js,manifest.json,styles.css} /path/to/your/vault/.obsidian/plugins/kioku/

3. Enable the plugin in Obsidian:

   • Open Obsidian.

   • Go to Settings -> Community plugins.

   • Click Reload (Reload icon) to detect the new plugin.

   • Toggle the switch next to Kioku MCP Bridge.

Environment Variables

Available MCP Tools

117 tools organized into 18 classes. For the full inventory with parameters, see docs/commands-reference.md.

Classes outside the core (query, write, utilities) are enabled or disabled by capability groups in {vault}/.kioku/config.yml — see docs/vault-config.md.

MCP Prompts & Resources

Besides the 116 tools, Kioku exposes the other two MCP primitives (SDK ModelContextProtocol 1.4.0). The full inventory lives alongside the tools inventory in docs/commands-reference.md.

Prompts — curated workflows that appear as native slash commands in any MCP client (Claude Code, Cursor, VS Code):

Resources — allow mounting vault content as context without spending a tool call:

resources/list returns only the ~20 most recent notes (not all 5000+ in the vault) — use the kioku://note/{path} resource template to read any note by its path.

Integrated Obsidian Plugins (via Plugin Bridge)

Project Status

• v1 (stdio): ✅ Complete — core tools + 22 plugin bridge commands

• v2 (HTTP-SSE): ✅ Complete — dual transport, Ollama embeddings, Bearer Token auth, VM deployment

• v3 (Ecosystem Tools): ✅ Complete — 102 tools across 17 classes: templates, tasks, Zettelkasten, CSS theming, assets, Git, restore, graph

License

MIT — see LICENSE