@kireo/mcp-server

@kireo/mcp-server

Long-term memory for any MCP-compatible AI tool (Claude Code, Cursor, Windsurf, Cline, Zed, Continue …).

Quickstart

• Get an API key at https://app.kireo.app/app/api-keys (ki_sk_…).
• Add this MCP server to your host. Claude Code — run:

claude mcp add kireo --scope user --env KIREO_API_KEY=ki_sk_xxx -- npx -y --package=@kireo/mcp-server kireo-mcp

Two details in that line are load-bearing, both verified against claude 2.1.220 and npm 11 on 2026-08-03:

• --package=@kireo/mcp-server kireo-mcp, not @kireo/mcp-server. This package ships two binaries (kireo, kireo-mcp), neither named after the package, so npx -y @kireo/mcp-server cannot pick one and fails with could not determine executable to run.
• --package=, not the short -p. A bare -p after -- gets swallowed by the claude mcp add option parser, which then rejects its own flag: claude mcp add kireo --env … -- npx -y -p @kireo/mcp-server kireo-mcp errors with unknown option '--env'. The long form parses cleanly.

Drop --scope user if you only want it in the current project. Alternatively, check a project-scoped .mcp.json into your repo root with the same shape (inside JSON args the short -p is fine — it goes straight to npx and never reaches the claude parser):

// .mcp.json (project root)
{
  "mcpServers": {
    "kireo": {
      "command": "npx",
      "args": ["-y", "--package=@kireo/mcp-server", "kireo-mcp"],
      "env": { "KIREO_API_KEY": "ki_sk_xxx" }
    }
  }
}

• Restart the host. You now have 8 tools available to the AI:

Tool	Purpose
memory_save	Persist a long-term memory
memory_search	Hybrid semantic + keyword search
memory_recall	Replay recent/important memories
memory_get	Fetch by id
memory_update	Patch fields
memory_delete	Soft/hard delete
memory_list_namespaces	Enumerate namespaces
memory_health	Probe service

Configuration

Sources are merged in order: CLI args > env > ~/.kireo/config.json.

ENV / CLI	Default	Description
KIREO_API_KEY / --api-key	required	Bearer token (ki_sk_…).
KIREO_API_URL / --api-url	https://api.kireo.app	Override for self-host.
KIREO_REQUEST_TIMEOUT_MS / --timeout	60000	Per-request timeout in ms, max 300000 (env alias: KIREO_TIMEOUT_MS).
KIREO_RETRY_MAX_ATTEMPTS	3	5xx/429 retries (alias: KIREO_RETRY_MAX).
KIREO_RETRY_BASE_MS	200	Exponential backoff base.
KIREO_TELEMETRY	1	Set to 0 to disable device-id header.
KIREO_LOG_LEVEL	info	debug / info / warn / error / silent.
KIREO_PROXY_URL	none	HTTP(S) proxy.
KIREO_ACCEPT_LANGUAGE	en	Locale for error hints.

Logs land in ~/.kireo/logs/ on all platforms (macOS, Linux, Windows).

Indexing local code

Index a repository's symbols (functions / classes / methods) into a code-<repo> namespace so the AI can recall them via memory_search:

export KIREO_API_KEY=ki_sk_xxx
npx -y -p @kireo/mcp-server kireo index ./ --repo my-app

Indexing is incremental — only changed files are re-sent on subsequent runs.

Flag	Default	Description
--repo <name>	directory basename	Repo name → code-<name> namespace.
--batch-size <n>	100	Symbols per upload batch (1..100). Lower it if a batch times out.
--timeout <ms>	60000	Per-request timeout (max 300000).
--api-key / --api-url / --namespace / --log-level / --no-telemetry	—	Same as the config table above; CLI flags override env.

Run kireo --help for the full usage text. --help and --version never touch the network or the filesystem and don't require an API key. If a batch upload times out, re-running the same command is safe: the server dedupes identical symbols, so retries won't create duplicates.

Host setup

• Claude Code
• Cursor
• Windsurf

Privacy

Set KIREO_TELEMETRY=0 to drop the X-Device-Id header. We never read your code; only the explicit content you pass to memory_save reaches the API.

Troubleshooting

• AUTH_INVALID_KEY → rotate your key at https://app.kireo.app/app/api-keys.
• QUOTA_EXCEEDED → upgrade or wait for next billing cycle.
• Tools missing in your host → run npx @modelcontextprotocol/inspector node $(npm root -g)/@kireo/mcp-server/bin/kireo-mcp.cjs to verify locally.

License

MIT