kioku-mcp-server 3.0.1

{
  "inputs": [
    {
      "type": "promptString",
      "id": "KIOKU_VAULT_PATH",
      "description": "Absolute path to the Obsidian vault root."
    },
    {
      "type": "promptString",
      "id": "KIOKU_MAX_RESULTS",
      "description": "Maximum number of search results returned by query tools."
    },
    {
      "type": "promptString",
      "id": "KIOKU_TRANSPORT",
      "description": "MCP transport value: stdio or http. The http value selects Streamable HTTP."
    },
    {
      "type": "promptString",
      "id": "KIOKU_HTTP_HOST",
      "description": "Host or interface used by the Streamable HTTP listener."
    },
    {
      "type": "promptString",
      "id": "KIOKU_HTTP_PORT",
      "description": "Port used by the Streamable HTTP listener."
    },
    {
      "type": "promptString",
      "id": "KIOKU_API_KEY",
      "description": "Bearer token for Streamable HTTP; required for non-loopback bindings unless the unsafe override is explicitly enabled."
    },
    {
      "type": "promptString",
      "id": "KIOKU_HTTP_ALLOWED_ORIGINS",
      "description": "Comma-separated exact browser origins accepted by Streamable HTTP."
    },
    {
      "type": "promptString",
      "id": "KIOKU_HTTP_TRUSTED_PROXIES",
      "description": "Comma-separated proxy IP addresses trusted to supply forwarded headers."
    },
    {
      "type": "promptString",
      "id": "KIOKU_ALLOW_INSECURE_HTTP",
      "description": "Unsafe override that permits a non-loopback Streamable HTTP listener without an API key."
    },
    {
      "type": "promptString",
      "id": "KIOKU_HTTP_MAX_REQUEST_BODY_BYTES",
      "description": "Maximum accepted MCP HTTP request body size in bytes."
    },
    {
      "type": "promptString",
      "id": "KIOKU_HTTP_REQUEST_TIMEOUT_SECONDS",
      "description": "Maximum execution time for an MCP POST request in seconds."
    },
    {
      "type": "promptString",
      "id": "KIOKU_OBSIDIAN_PORT",
      "description": "WebSocket port exposed by the optional Obsidian plugin bridge."
    },
    {
      "type": "promptString",
      "id": "KIOKU_BRIDGE_TOKEN",
      "description": "Shared secret for the Obsidian bridge WebSocket; it must match the plugin setting."
    },
    {
      "type": "promptString",
      "id": "KIOKU_OLLAMA_URL",
      "description": "Base URL of the Ollama service used for embeddings and optional generation."
    },
    {
      "type": "promptString",
      "id": "KIOKU_EMBEDDING_MODEL",
      "description": "Ollama embedding model."
    },
    {
      "type": "promptString",
      "id": "KIOKU_GEN_MODEL",
      "description": "Ollama model for optional local generation tools; unset disables generation."
    },
    {
      "type": "promptString",
      "id": "KIOKU_INDEX_CONCURRENCY",
      "description": "Maximum concurrent vault indexing operations."
    },
    {
      "type": "promptString",
      "id": "KIOKU_EMBEDDING_CONCURRENCY",
      "description": "Maximum concurrent embedding requests."
    },
    {
      "type": "promptString",
      "id": "KIOKU_ALLOW_EXTERNAL_READS",
      "description": "Allows read-only imports outside the vault only from explicitly configured roots."
    },
    {
      "type": "promptString",
      "id": "KIOKU_EXTERNAL_READ_ROOTS",
      "description": "Platform-path-separator-delimited roots allowed for external read-only imports."
    },
    {
      "type": "promptString",
      "id": "KIOKU_ALLOW_PERMANENT_DELETE",
      "description": "Enables irreversible deletion; soft delete remains available when false."
    },
    {
      "type": "promptString",
      "id": "KIOKU_ENABLE_METRICS",
      "description": "Enables in-memory tool-call counters; note contents are never recorded."
    },
    {
      "type": "promptString",
      "id": "KIOKU_ENABLE_TRACING",
      "description": "Enables W3C-compatible coordination activities; Kioku configures no trace exporter."
    },
    {
      "type": "promptString",
      "id": "KIOKU_SENTRY_DSN",
      "description": "Opt-in Sentry DSN for crash reporting."
    }
  ],
  "servers": {
    "kioku-mcp-server": {
      "type": "stdio",
      "command": "dnx",
      "args": ["kioku-mcp-server@3.0.1", "--yes"],
      "env": {
        "KIOKU_VAULT_PATH": "${input:KIOKU_VAULT_PATH}",
        "KIOKU_MAX_RESULTS": "${input:KIOKU_MAX_RESULTS}",
        "KIOKU_TRANSPORT": "${input:KIOKU_TRANSPORT}",
        "KIOKU_HTTP_HOST": "${input:KIOKU_HTTP_HOST}",
        "KIOKU_HTTP_PORT": "${input:KIOKU_HTTP_PORT}",
        "KIOKU_API_KEY": "${input:KIOKU_API_KEY}",
        "KIOKU_HTTP_ALLOWED_ORIGINS": "${input:KIOKU_HTTP_ALLOWED_ORIGINS}",
        "KIOKU_HTTP_TRUSTED_PROXIES": "${input:KIOKU_HTTP_TRUSTED_PROXIES}",
        "KIOKU_ALLOW_INSECURE_HTTP": "${input:KIOKU_ALLOW_INSECURE_HTTP}",
        "KIOKU_HTTP_MAX_REQUEST_BODY_BYTES": "${input:KIOKU_HTTP_MAX_REQUEST_BODY_BYTES}",
        "KIOKU_HTTP_REQUEST_TIMEOUT_SECONDS": "${input:KIOKU_HTTP_REQUEST_TIMEOUT_SECONDS}",
        "KIOKU_OBSIDIAN_PORT": "${input:KIOKU_OBSIDIAN_PORT}",
        "KIOKU_BRIDGE_TOKEN": "${input:KIOKU_BRIDGE_TOKEN}",
        "KIOKU_OLLAMA_URL": "${input:KIOKU_OLLAMA_URL}",
        "KIOKU_EMBEDDING_MODEL": "${input:KIOKU_EMBEDDING_MODEL}",
        "KIOKU_GEN_MODEL": "${input:KIOKU_GEN_MODEL}",
        "KIOKU_INDEX_CONCURRENCY": "${input:KIOKU_INDEX_CONCURRENCY}",
        "KIOKU_EMBEDDING_CONCURRENCY": "${input:KIOKU_EMBEDDING_CONCURRENCY}",
        "KIOKU_ALLOW_EXTERNAL_READS": "${input:KIOKU_ALLOW_EXTERNAL_READS}",
        "KIOKU_EXTERNAL_READ_ROOTS": "${input:KIOKU_EXTERNAL_READ_ROOTS}",
        "KIOKU_ALLOW_PERMANENT_DELETE": "${input:KIOKU_ALLOW_PERMANENT_DELETE}",
        "KIOKU_ENABLE_METRICS": "${input:KIOKU_ENABLE_METRICS}",
        "KIOKU_ENABLE_TRACING": "${input:KIOKU_ENABLE_TRACING}",
        "KIOKU_SENTRY_DSN": "${input:KIOKU_SENTRY_DSN}"
      }
    }
  }
}
                    
This package contains an MCP Server. The server can be used in VS Code by copying the generated JSON to your VS Code workspace's .vscode/mcp.json settings file.
dotnet tool install --global kioku-mcp-server --version 3.0.1
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local kioku-mcp-server --version 3.0.1
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=kioku-mcp-server&version=3.0.1
                    
nuke :add-package kioku-mcp-server --version 3.0.1
                    

Kioku MCP Server

Current package version: 3.0.1 · Documentation · Release notes · Source

Kioku is a local-first Model Context Protocol server that gives AI agents persistent, structured memory in an Obsidian vault. It lets MCP clients read, search, write, and organize ordinary Markdown and YAML-frontmatter files while keeping the vault under the user's control.

The server works headlessly: Obsidian does not need to be open for core note, search, project, indexing, work-session, or coordination operations. The separately released Kioku Obsidian plugin is optional and is required only for UI-aware commands and supported-plugin bridge operations.

Install or update

Install Kioku as a global .NET tool:

dotnet tool install --global kioku-mcp-server

Update an existing installation:

dotnet tool update --global kioku-mcp-server

Verify the installed command:

kioku --help

Kioku requires the path to an Obsidian vault. For a direct local launch:

export KIOKU_VAULT_PATH="/absolute/path/to/your/vault"
kioku

stdio is the default transport and is intended for desktop and CLI MCP clients. Kioku also supports authenticated Streamable HTTP for long-running or shared deployments.

Register an MCP client

A minimal client configuration starts kioku and supplies the vault path:

{
  "mcpServers": {
    "kioku": {
      "command": "kioku",
      "env": {
        "KIOKU_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

The repository also provides supported installers for Claude Code, Codex, OpenCode, and Antigravity. See the installation guide for client-specific configuration, Docker, source builds, and troubleshooting.

What Kioku provides

  • durable project context, decisions, plans, bugs, knowledge, and session handoffs;
  • bounded vault reads and guarded writes with structured error results;
  • full-text retrieval plus optional local Ollama embeddings and generation;
  • focused engineering and organization tools backed by readable Markdown;
  • capability-gated optional groups, including CSS, assets, bridge, plugin, and coordination;
  • local stdio and authenticated Streamable HTTP transports;
  • an optional Obsidian bridge without coupling server and plugin SemVer.

The default discovery profile contains the safe core surface. Optional capability groups must be enabled explicitly when an integration needs them. Treat tools/list as authoritative rather than assuming every possible tool is registered.

Kioku 3 migration

Kioku 3 changed public tool names, discovery profiles, structured results, and guarded mutation behavior. Integrations upgrading from 2.3.0 should follow the 2.3.0 to 3.0.0 migration guide before switching production clients.

The authoritative generated references are:

Security defaults

  • writes are constrained to the configured vault;
  • external reads and permanent deletion are disabled by default;
  • Streamable HTTP binds to loopback by default;
  • non-loopback HTTP requires an API key unless an explicit unsafe override is enabled;
  • browser origins and trusted proxies use exact allowlists;
  • bridge authentication uses a separate shared token;
  • optional local AI calls use the configured Ollama service.

Review the threat and privacy model and Streamable HTTP security guide before exposing Kioku outside a trusted local environment.

License

Kioku is released under the MIT License.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.