Kimi MCP Hub

One-click MCP server and skills manager for Kimi CLI -- like claude-mem but for connecting 25 MCP servers (Jira, GitHub, Slack, Obsidian, Datadog, Perplexity, Stripe, GitLab, DBHub, etc.), 57 AI skills (7 core + 7 frontend + 43 optional), persistent memory, and Claude Desktop import.

---

Table of Contents

• Install as a Kimi plugin (recommended)
• Install
  • One-liner with npx (recommended)
  • One-liner (curl / PowerShell)
  • From GitHub (pip) inside a venv
  • Clone + Install (development)
  • Requirements
  • Verify
  • Run the wizard
• Uninstall
• Quick Start
• Update
• Managing MCP Servers and Skills
• Repository Packing
• Pre-PR Code Review
• Obsidian Local Memory
• Advanced Memory Layer
• Install Claude/Codex Plugins
• Project-Level MCP Configuration
• Profiles
• Localization
• Remote MCP Server Setup
• OAuth Auto-Browser
• CLAUDE.md Compatibility
• All Commands
• Testing
• MCP Servers
• Skills
• Architecture

---

Install as a Kimi plugin (recommended)

Since Kimi Code CLI 0.23, kimi-mcp-hub ships as a native Kimi plugin (kimi.plugin.json). This installs MCP servers and all 58 skills without leaving Kimi CLI — no external terminal step, no manual config editing.

Inside a Kimi session:

/plugins install https://github.com/KalimeroMK/kimi-mcp-hub
/reload

What you get after /reload:

What	Servers	Action needed
Zero-config stdio servers	chrome-devtools, context7, playwright, desktop-commander, mobile	None — works immediately
Official remote OAuth servers	linear, jira, confluence, supabase, figma, stripe, gitlab, github	One login per server: /mcp-config login <name>
Skills	all 57	None — loaded from the plugin

Servers that need API keys or tokens (perplexity, slack, datadog, sentry, hubspot, postgres, gmail, ...) can be added in-session too:

/kimi-mcp-hub:add perplexity

The agent asks for the credential, writes ~/.kimi-code/mcp.json, and tells you when to /reload. Run /kimi-mcp-hub:setup anytime for a guided overview of what is ready, what needs a login, and what needs credentials.

Before opening a pull request, /kimi-mcp-hub:pre-pr-review reviews the current branch against its base branch and ends with a go/no-go verdict — see Pre-PR Code Review.

Migrating from the classic install: plugin MCP servers are namespaced (mcp__plugin-kimi-mcp-hub_<server>__*), so they coexist with older entries in ~/.kimi-code/mcp.json. Remove duplicates once with kimi-mcp-hub remove <server> to avoid seeing the same tools twice.

Persistent memory (SQLite + Obsidian hooks) still requires the Python package — install it via the classic method below and run kimi-mcp-hub init.

---

Install

One-liner with npx (recommended)

npx kimi-mcp-hub install

This creates an isolated Python virtual environment at ~/.kimi-mcp-hub/.venv, installs the package, and runs the interactive setup.

One-liner (curl / PowerShell)

# macOS / Linux (curl + pip from GitHub)
curl -fsSL https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.sh | bash

# macOS / Linux with auto CLAUDE.md support
curl -fsSL https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.sh | bash -s -- -y

# macOS / Linux with Obsidian local memory
curl -fsSL https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.sh | bash -s -- --with-obsidian

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.ps1 | iex

# Windows with auto CLAUDE.md support
iwr -useb https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.ps1 | & ([scriptblock]::create($_)) -Yes

# Windows with Obsidian local memory
iwr -useb https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.ps1 | & ([scriptblock]::create($_)) -Yes -WithObsidian

From GitHub (pip) inside a venv

# Direct from GitHub -- no clone needed
python3 -m venv ~/.kimi-mcp-hub/.venv
~/.kimi-mcp-hub/.venv/bin/pip install --upgrade git+https://github.com/KalimeroMK/kimi-mcp-hub.git
ln -s ~/.kimi-mcp-hub/.venv/bin/kimi-mcp-hub ~/.local/bin/kimi-mcp-hub

Clone + Install (development)

git clone https://github.com/KalimeroMK/kimi-mcp-hub.git
cd kimi-mcp-hub
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Requirements

• Python 3.10+
• Node.js + npm/npx (for MCP servers that need it)
• Kimi CLI installed
• Optional: Docker (for some servers)

Verify

kimi-mcp-hub --version
# -> kimi-mcp-hub, version 0.7.0

On first run you'll see:

Kimi MCP Hub v0.7.0 installed successfully!

25 MCP servers available
57 AI skills for better coding
1  Persistent memory system

To get started:
  kimi-mcp-hub init    -- interactive wizard
  kimi-mcp-hub welcome -- detailed overview
  kimi-mcp-hub status  -- status check
  kimi-mcp-hub doctor  -- system health check

Run the wizard

kimi-mcp-hub init

This walks you through:

1. MCP Servers -- Chrome DevTools, Context7, and Playwright are auto-installed if npx is available; pick additional services manually
2. Skills -- install AI behavior patterns
3. Memory -- enable persistent cross-session memory

---

Uninstall

# Full reset
rm -f ~/.kimi-code/mcp.json
rm -rf ~/.kimi-code/skills/
rm -rf ~/.kimi-mcp-hub/
rm -rf ~/.config/kimi-mcp-hub/
rm -f ~/.local/bin/kimi-mcp-hub
rm -f ~/.local/bin/kmcp

# Or use the CLI
kimi-mcp-hub remove jira      # remove one server
kimi-mcp-hub remove github    # remove another

Complete reinstall:

rm -rf ~/.kimi-code/mcp.json ~/.kimi-code/skills/ ~/.kimi-mcp-hub/
bash -c "$(curl -fsSL https://raw.githubusercontent.com/KalimeroMK/kimi-mcp-hub/main/install/install.sh)"
kimi-mcp-hub init

---

Quick Start

# Show welcome banner + status
kimi-mcp-hub

# Check system health
kimi-mcp-hub doctor

# Full interactive setup
kimi-mcp-hub init

# Non-interactive setup (auto-installs core + frontend skills, memory, and claude-compat)
kimi-mcp-hub init --yes

# Auto-load CLAUDE.md and CLAUDE.local.md at every session start
kimi-mcp-hub claude-compat
kimi-mcp-hub claude-compat --yes

# Add servers individually
kimi-mcp-hub add jira
kimi-mcp-hub add github
kimi-mcp-hub add slack
kimi-mcp-hub add supabase
kimi-mcp-hub add perplexity
kimi-mcp-hub add gitlab
kimi-mcp-hub add stripe
kimi-mcp-hub add figma-context
kimi-mcp-hub add desktop-commander
kimi-mcp-hub add dbhub
kimi-mcp-hub add mobile

# Update to the latest version
kimi-mcp-hub update

# Add and authorize OAuth servers -- like Claude Code CLI
kimi-mcp-hub add github   # choose oauth-device to configure and authorize
kimi-mcp-hub add figma

# GitLab and Stripe are official remote MCP servers; authorize via Kimi CLI:
# kimi mcp auth gitlab
# kimi mcp auth stripe

# For other official remote MCP servers, Kimi CLI handles the popup:
# /mcp-config login jira
# /mcp-config login linear
# /mcp-config login confluence
# /mcp-config login supabase

# See everything configured
kimi-mcp-hub list
kimi-mcp-hub status
kimi-mcp-hub welcome
kimi-mcp-hub notify

# Fix broken configs after package updates
kimi-mcp-hub repair

# Per-project MCP configuration
kimi-mcp-hub add --project linear   # save to ./.kimi/mcp.json
kimi-mcp-hub sync                   # merge project config into global config

# Import from Claude Desktop
kimi-mcp-hub import-claude

# Manage skills
kimi-mcp-hub list-skills
kimi-mcp-hub install-skill docker-pro

# Test a server
kimi-mcp-hub test github

# Manage Obsidian vaults for local memory
kimi-mcp-hub obsidian status
kimi-mcp-hub obsidian add                    # standard location for this OS
kimi-mcp-hub obsidian add ~/Documents/MyVault
kimi-mcp-hub obsidian auto
kimi-mcp-hub obsidian list
kimi-mcp-hub obsidian remove myvault
kimi-mcp-hub obsidian set-default myvault
kimi-mcp-hub obsidian sync-templates --templates-dir ./templates myvault

---

Update

Update kimi-mcp-hub to the latest version in the isolated venv:

kimi-mcp-hub update

This upgrades the package from GitHub and refreshes the ~/.local/bin symlinks. Development installs (git checkouts) are detected and skipped.

---

Managing MCP Servers and Skills

Skills

Skills are toggled inside Kimi CLI:

/skill:caveman
/skill:headroom
/skill:code-review

• Core skills (karpathy, superpowers, caveman, headroom, context-mode, cybersecurity, kimi-mcp-hub-status) activate automatically on every Kimi start.
• Install more skills from the terminal:

  kimi-mcp-hub install-skill docker-pro
  

MCP Servers

Tip: with the Kimi plugin install, 13 servers and all skills are available without these manual steps.

MCP servers are enabled outside Kimi CLI, in your regular terminal:

# Stdio / API-key servers
kimi-mcp-hub add github   # choose PAT or oauth-device
kimi-mcp-hub add slack

# Official remote OAuth servers can also be connected inside Kimi:
# /mcp-config login linear
# /mcp-config login jira
# /mcp-config login supabase

linear also supports an API-key stdio mode via kimi-mcp-hub add linear → choose api-key.

When you add an npx-based server for the first time, kimi-mcp-hub checks if the package is already installed and prompts to install it globally. This prevents the 30-second timeout that can happen when Kimi CLI tries to launch a not-yet-cached npx package.

After adding a server, restart Kimi CLI (exit → kimi) so it picks up the new config.

For a detailed walkthrough of official remote OAuth servers (Linear, Jira, Confluence, Supabase, Figma, Stripe, GitLab), see Remote MCP Server Setup.

---

Repository Packing

Pack a repository into a single AI-friendly markdown file for context windows.

# Pack the current directory
kimi-mcp-hub pack

# Pack a specific repository
kimi-mcp-hub pack /path/to/repo

# Include only Python files
kimi-mcp-hub pack -i '*.py' -i '**/*.py'

# Exclude patterns
kimi-mcp-hub pack -e '*.test.js' -e 'dist/'

# Increase size budget and write to a file
kimi-mcp-hub pack --max-size 1048576 -o repo.md

• .gitignore is respected by default; use --no-gitignore to disable.
• Binary files appear in the generated file tree but are omitted from code blocks.
• Files that would push the output over the size budget are listed in a warning and skipped.
• Use - as the output path to force stdout (-o -).

---

Pre-PR Code Review

Review the current branch the way a reviewer would, before the PR exists.

Inside a Kimi session:

/kimi-mcp-hub:pre-pr-review
/kimi-mcp-hub:pre-pr-review quick          # one pass, no sub-agents
/kimi-mcp-hub:pre-pr-review deep           # every sub-agent
/kimi-mcp-hub:pre-pr-review focus src/auth # one path only
/kimi-mcp-hub:pre-pr-review develop        # compare against another base

The command collects the diff, dispatches explore / coder / plan sub-agents over it, runs the project's fast linter on the changed files only, and finishes with a verdict: ready to open, open with follow-ups, or fix first. It never edits, stages, commits, pushes, or opens the PR.

The diff collection is a separate command, so it is deterministic rather than re-derived by an agent each time:

# What the PR would contain: merge-base..HEAD, the same set GitHub shows
kimi-mcp-hub review-context

# Compare against an explicit base
kimi-mcp-hub review-context --base develop

# Summary without the diff body, or machine-readable
kimi-mcp-hub review-context --no-diff
kimi-mcp-hub review-context --json

# Include work that is not committed yet
kimi-mcp-hub review-context --include-uncommitted

• The base branch is resolved from an open PR (gh), then origin/HEAD, then origin/main, origin/master, origin/develop, origin/trunk, then a local branch. The source is reported, so you can tell a detected base from one you asked for.
• Uncommitted files are listed but kept out of the diff by default -- they are not part of the PR. When nothing is committed against the base, the working tree is reviewed instead, including the content of untracked files (git diff alone never shows those).
• Warnings call out the ways a review can silently look at the wrong thing: a shallow clone with no merge base, a suspiciously long commit range, a criss-cross history with several merge bases, a stale local base branch, or a fork PR.
• The diff body is truncated at a file boundary rather than mid-hunk, so a truncated diff never describes a change that was not made. The file list stays complete either way.
• Everything is read-only: no fetch, no checkout, no config writes.

---

Obsidian Local Memory

Obsidian vaults can be used as local memory and knowledge bases. The obsidian command group manages vault paths without needing the full init wizard.

# Show configured vaults and their status
kimi-mcp-hub obsidian status

# Add a vault at the standard location for this OS (scaffolds it if needed)
kimi-mcp-hub obsidian add

# ...or at a path you choose
kimi-mcp-hub obsidian add ~/Documents/MyVault

# Auto-create a project vault for the current git repo
kimi-mcp-hub obsidian auto

# List configured vaults
kimi-mcp-hub obsidian list

# Remove a vault from the config by slug (files are kept)
kimi-mcp-hub obsidian remove myvault

# Change the default memory vault
kimi-mcp-hub obsidian set-default myvault

# Copy templates into a vault (no templates are bundled; pass your own directory)
kimi-mcp-hub obsidian sync-templates --templates-dir ./templates myvault

The first vault added is set as the default memory vault -- without one, session notes are written nowhere. After adding a vault, restart Kimi CLI so the Obsidian MCP server picks it up.

The standard location is <Documents>/Kimi-Memory, where <Documents> is resolved per OS: ~/Documents on macOS and Windows (including a OneDrive-redirected folder), and whatever xdg-user-dirs reports on Linux -- which is localized, so a non-English desktop gets its real Documents folder rather than a second English one. On a machine with no Documents folder at all (headless Linux, WSL, containers) the vault goes to ~/Kimi-Memory instead.

If Obsidian tool calls time out (MCP error -32001: Request timed out), the server entry was written before the switch to obsidian-mcp@2: the old positional vault form makes v2 hang rather than fail, so the client reports a timeout instead of a config error. Run kimi-mcp-hub repair to rewrite it. The v2 tool names also differ -- there is no list-available-vaults, it is obsidian_list_vaults, one of 12 obsidian_* tools.

Project-specific memory

When working across multiple repositories, kimi-mcp-hub obsidian auto detects the current git repo and creates/switches to a project-specific vault at <repo-root>/<RepoName>-Memory. If the vault lives inside the repo, the command also adds it to .gitignore so it is never committed. To make this automatic whenever you start Kimi, add a shell wrapper to your ~/.zshrc:

k() {
  kimi-mcp-hub obsidian auto >/dev/null 2>&1
  kimi "$@"
}

Then use k instead of kimi. Each project gets its own memory vault automatically.

Note that obsidian auto also makes that project vault the default memory vault, so with this wrapper the default follows whichever repo you are in rather than staying on the one the installer created. That is the point of the wrapper -- but if you would rather keep a single vault, do not use it, and set the vault once with kimi-mcp-hub obsidian set-default <slug>.

---

Advanced Memory Layer

In addition to Obsidian notes, kimi-mcp-hub keeps a local, long-term memory store for facts, preferences, and project context. Memories are saved to a SQLite database and are searchable from the CLI. Project-scoped memories are automatically injected at session start when the working directory matches.

# Save a user preference
kimi-mcp-hub memory add "Use ruff for linting" --category user --tags linting

# Save project context for the current directory
kimi-mcp-hub memory add "API base URL is https://api.example.com" --category project

# Search all memories
kimi-mcp-hub memory search "ruff"

# List recent memories
kimi-mcp-hub memory list

# Delete a memory by ID
kimi-mcp-hub memory forget 3

Project memories (--category project) are injected into the session context whenever you start Kimi in the matching project directory. This is useful for base URLs, coding conventions, or reminders that should apply to a specific codebase.

Memory as an MCP server

Session-start injection can only tell the model what was recent. The bundled kimi-memory MCP server lets it search the whole history mid-session. It is registered automatically when memory is enabled, runs locally against the same SQLite file, and needs no API key or network access.

Tool	Purpose
memory_search	Full-text search (mode: keyword, semantic or hybrid), returns a compact index (id, time, type, title)
memory_timeline	Show what happened immediately before and after one hit
memory_get	Fetch the full text of specific ids
memory_summarize	Record a summary of the current conversation (called by the model when a hook asks)
memory_save	Store a durable project note from inside the session

The three read tools are a deliberate funnel: search returns titles only, so the model narrows down cheaply and pulls full bodies just for the handful of ids it actually needs, instead of paying for every match.

Results are scoped to the current project by default; pass all_projects: true to search everything.

# Registered automatically by `init`, or add it explicitly:
kimi-mcp-hub add kimi-memory

Browsing memory in the browser

A read-only web UI over the same database: search, filter by project and type, page through observations, and read full entries side by side.

kimi-mcp-hub memory viewer

The default address is http://127.0.0.1:8765 and the browser opens by itself. That form runs in the foreground until you press Ctrl+C.

Open the printed link once. It carries an access token:

Memory viewer: http://127.0.0.1:8765/?token=Xk7pQ2mR9vL4nT8wZ1cY3hB6
   Database: ~/.config/kimi-mcp-hub/memory.db
   Opening this link authorizes this browser for good.
   Local only. Press Ctrl+C to stop.

That visit leaves a session cookie (HttpOnly, SameSite=Strict) and strips the token back out of the address bar. From then on plain http://127.0.0.1:8765 works — bookmark that. A browser that has never seen the link gets the page but no data, and is told how to authorize itself.

The token lives in viewer-token (mode 0600) and survives restarts, so the cookie stays valid. --rotate-token replaces it and locks out every browser and link that had the old one.

Keeping it always on

Turn on autostart and the viewer comes up with every Kimi session and stays up after it — the same model claude-mem uses:

kimi-mcp-hub memory viewer --autostart

From then on the URL is always live; nothing opens a browser tab, so it stays out of your way. Autostart is off until you ask for it, so installing the package never leaves an HTTP server running behind your back.

Manage it directly at any time:

kimi-mcp-hub memory viewer --daemon     # start in the background now
kimi-mcp-hub memory viewer --status     # running? which pid? what URL?
kimi-mcp-hub memory viewer --stop       # stop it
kimi-mcp-hub memory viewer --no-autostart

$ kimi-mcp-hub memory viewer --status
running  pid 25318  (responding)
   http://127.0.0.1:8765/?token=4oNeh0V3ZAkvFP021TETUeqjq6T1YLSt
   Autostart with Kimi sessions: on
   Database: ~/.config/kimi-mcp-hub/memory.db

The session hook only checks a pidfile when the viewer is already up, which costs no measurable time; when it is down it spawns the process and returns without waiting. A viewer that fails to start never fails a Kimi session.

Change the port with --port (remembered when combined with --autostart). If the port belongs to another process the command says so instead of claiming it, and a pidfile left behind by a crash or a reboot is detected as stale and cleaned up on the next start.

Headless machines, SSH, and WSL

On a server, a container, or an SSH session there is no browser to open. The command detects this, prints the reason, and tells you how to reach it:

Memory viewer: http://127.0.0.1:8765/?token=pbHgoD8eyt59nNTf8_KXt2gKWyjXed2x
   Database: ~/.config/kimi-mcp-hub/memory.db
   Local only. Press Ctrl+C to stop.
Could not open a browser (no graphical display detected).
   Open the URL above yourself, or forward the port:
   ssh -L 8765:127.0.0.1:8765 <user>@<host>

Auto-open is attempted when DISPLAY or WAYLAND_DISPLAY is set, or when BROWSER names a launcher — which is what makes it work under WSL (BROWSER=wslview). On macOS and Windows it just works.

Run the SSH command from your laptop, then open the printed URL there: the port is forwarded through the tunnel, so the viewer still only ever listens on the server's loopback interface.

Why it is locked down

The database holds raw tool output, which can contain secrets. Four things guard it, and they cover different attacks:

Control	Stops
Loopback bind	Anything off this machine
No CORS headers	A web page you visit reading the responses
Host header check	The same, via DNS rebinding, which defeats origin checks
Access token	Other user accounts on this machine

The first three need no cooperation from you. The token is the one that costs convenience, and it buys exactly one thing: a shared host is a host where every other account can reach 127.0.0.1:8765 and read your whole history. The session cookie removes the friction without giving that up.

On a machine only you can log into, that last row may not be worth anything:

kimi-mcp-hub memory viewer --no-token     # plain http://127.0.0.1:8765, no cookie
kimi-mcp-hub memory viewer --token        # back on

The other three controls stay in force either way. There is deliberately no flag to expose the viewer on the network — SSH forwarding is the supported way to reach it remotely.

What gets captured

Hooks record tool calls as observations, with three rules that keep the store useful rather than merely large:

• Project attribution — every observation is tagged with the resolved working directory, so recall never mixes repositories.
• Deduplication — an identical result from the same tool in the same session is stored once.
• Noise filtering — read-only navigation tools (Read, Glob, Grep, LS, WebFetch, …) stay on the timeline but their output body is dropped. Set KIMI_MEMORY_CAPTURE_ALL=1 to keep everything, or extend the list with KIMI_MEMORY_SKIP_TOOLS=Bash,MyTool.

At the end of a session the LLM summary is stored as a searchable observation, which is what later sessions retrieve — both at session start and, per prompt, through the UserPromptSubmit hook.

Free, offline session summaries

Memory works with no API key, no account and no external service. Three layers build the session summary, in this order:

1. The active Kimi model writes it. The hooks never see the assistant's answers, but the model running the session does. When enough has happened (summary_every, default 6 new observations) the Stop hook asks it, once, to call memory_summarize with what was asked, what was done, the key content of anything that exists only in chat, decisions and open items. It costs one short turn from the quota you already have; with no quota left the request just fails and nothing is spent. Turn it off with summary_by_model = false under [memory] in ~/.kimi-code/config.toml.
2. An automatic summary is always kept as a floor. It is built from the session's own prompts, files written and commands run, so a session is recallable even when the model never answers the request.
3. An LLM provider, optional -- see below. A provider summary, when it works, replaces the model-written one and no request is made.

Each tool call is stored as a readable label (Edit: src/app.py, Bash: pytest -q) rather than Used Bash; secrets in commands are redacted and <private> spans dropped. A session keeps a single row that is refreshed, and a model- or provider-written summary is never overwritten by the automatic one.

Semantic search (optional)

memory_search accepts mode: "semantic" or "hybrid" (keyword and vector results merged). It needs the sqlite-vec extra and an OpenAI-compatible embeddings endpoint; without either, it silently falls back to keyword search.

pip install "kimi-mcp-hub[vec]"

[memory]
embedding_model = "text-embedding-3-small"   # or KIMI_MEMORY_EMBEDDING_MODEL
summary_base_url = "https://api.openai.com/v1"  # shared with summaries
summary_api_key = "..."

The viewer also streams new observations live over Server-Sent Events at /api/stream (same token or cookie as the rest of the viewer).

LLM-powered session summaries (optional)

By default, every session is saved as a raw observation note in your default Obsidian vault. You can also enable LLM-generated summaries that extract the goal, key decisions, files/tools touched, and open TODOs.

# Configure an OpenAI-compatible provider
kimi-mcp-hub memory config-summary --api-key sk-... --model gpt-4o-mini

# Or use an environment variable (safer — avoids shell history)
export KIMI_MEMORY_SUMMARY_API_KEY=sk-...
kimi-mcp-hub memory config-summary --model gpt-4o-mini

# Interactive prompt (key is hidden)
kimi-mcp-hub memory config-summary

# Disable summaries but keep raw notes
kimi-mcp-hub memory config-summary --api-key sk-... --disabled

Supported providers include OpenAI, OpenRouter, and local servers such as Ollama or LM Studio. A local localhost endpoint needs no key, so summaries can run entirely on your machine:

kimi-mcp-hub memory config-summary --model llama3.1 --base-url http://localhost:11434/v1

If no key is configured or the LLM call fails, kimi-mcp-hub falls back to the raw observation note.

After a session you will find two notes in <vault>/Sessions/:

• YYYY-MM-DD-HHMMSS-<session>.md — raw observations
• YYYY-MM-DD-HHMMSS-<session>-summary.md — LLM-generated summary

---

Install Claude/Codex Plugins

Kimi CLI now supports lifecycle hooks (PreToolUse, PostToolUse, Stop, etc.) via ~/.kimi-code/config.toml. Because Kimi uses the same JSON wire protocol as Claude Code and Codex, plugins written for those agents can be adapted automatically.

# Install Ponytail (reduces over-engineering)
kimi-mcp-hub install-plugin DietrichGebert/ponytail

# From a full URL
kimi-mcp-hub install-plugin https://github.com/DietrichGebert/ponytail

# From a local checkout
kimi-mcp-hub install-plugin ./ponytail

# Non-interactive reinstall/update
kimi-mcp-hub install-plugin DietrichGebert/ponytail --yes

install-plugin does the following:

1. Clones the repo to ~/.config/kimi-mcp-hub/plugins/<name>/ (or copies a local directory)
2. Discovers the plugin manifest among supported formats:
   • hooks.json / hooks/hooks.json / hooks/claude-codex-hooks.json
   • .claude/settings.json
   • .codex/hooks.json
   • .claude-plugin/plugin.json (Claude marketplace format)
   • gemini-extension.json
3. Converts discovered hooks to Kimi [[hooks]] entries in ~/.kimi-code/config.toml
4. Expands ${PLUGIN_ROOT}, ${CLAUDE_PLUGIN_ROOT}, and ${CLAUDE_CODE_PLUGIN_ROOT} to the install directory
5. Relativizes hardcoded absolute paths that still point inside the plugin directory so commands stay portable
6. Merges the plugin's AGENTS.md into ~/.kimi-code/AGENTS.md (idempotent by marker)
7. Copies plugin skills into ~/.kimi-code/skills/

What this unlocks

1. Ponytail works immediately — reduces over-engineering in every project.
2. Security hooks — block edits to .env files or dangerous rm commands.
3. Auto-format / auto-lint hooks after every WriteFile.
4. Stop hooks — verify tests passed before the session ends.
5. kimi-mcp-hub becomes a hub for agent extensions, not just an MCP manager.

Tool-name mapping

Claude/Codex	Kimi matcher
Write	WriteFile|StrReplaceFile
Edit	Edit|StrReplaceFile
Read	ReadFile
Bash	Shell|Bash

After installing a plugin, restart Kimi CLI for the hooks to take effect.

Managing installed plugins

Plugins installed from GitHub can be updated and removed through the CLI:

# Pull latest changes for a git plugin, or re-copy a local plugin
kimi-mcp-hub update-plugin ponytail

# Remove a plugin completely
kimi-mcp-hub uninstall-plugin ponytail

update-plugin re-runs the install merge, so new hooks, skills, and AGENTS.md sections are applied automatically. uninstall-plugin removes the plugin directory, deletes its hooks from ~/.kimi-code/config.toml, removes any skills it installed, and removes its section from ~/.kimi-code/AGENTS.md.

---

Project-Level MCP Configuration

If you work on multiple projects that need different MCP accounts, you can store MCP servers inside each project. The example below adds Linear's official remote OAuth server:

cd my-project
kimi-mcp-hub add --project linear   # choose the default "official-oauth" mode
kimi-mcp-hub sync

Once a project has a .kimi/ directory, project mode becomes automatic — add, remove, auth, and init write to ./.kimi/mcp.json without needing --project. Use --global to explicitly target the global config instead:

kimi-mcp-hub add linear          # inside a .kimi/ project -> writes ./.kimi/mcp.json
kimi-mcp-hub add --global slack  # force the global ~/.kimi-code/mcp.json

This creates:

my-project/
└── .kimi/
    ├── mcp.json          # server config
    └── mcp.env           # only needed for API-key / stdio servers (add this to .gitignore)

.kimi/mcp.json example (Linear official remote OAuth — no env):

{
  "mcpServers": {
    "linear": {
      "transport": "http",
      "url": "https://mcp.linear.app/mcp",
      "auth": "oauth"
    }
  }
}

.kimi/mcp.env is only required for servers that store secrets in environment variables (for example, API-key stdio servers such as Perplexity or a GitHub PAT). OAuth servers like Linear keep tokens inside Kimi CLI's own secure storage and do not need a project .env file.

Switching between projects

When you switch projects, run sync to rewrite the global ~/.kimi-code/mcp.json with that project's servers:

cd project-a && kimi-mcp-hub sync   # global config now uses project-a's Linear
cd project-b && kimi-mcp-hub sync   # global config now uses project-b's Linear

Project servers override global servers with the same name. Global servers that are not overridden remain available.

Auto-sync on every Kimi start (shell-init)

To make sync automatic, install the shell wrapper:

kimi-mcp-hub shell-init --install   # appends to ~/.zshrc or ~/.bashrc

Then use k instead of kimi. Every Kimi start inside a project with .kimi/mcp.json syncs that project's servers first. kimi-mcp-hub shell-init without --install just prints the snippet.

Project skills (.kimi/skills.json)

A project can also declare the skills it needs:

kimi-mcp-hub install-skill --project php-pro   # installs now + records in .kimi/skills.json

kimi-mcp-hub sync installs any missing skills from .kimi/skills.json, so teammates who clone the repo get them on their first sync. Commit .kimi/skills.json (it contains no secrets).

Commands with --project / --global

kimi-mcp-hub init --project          # save wizard servers to current project
kimi-mcp-hub add --project perplexity # add API-key server to current project
kimi-mcp-hub add --project linear    # add official remote OAuth server to current project
kimi-mcp-hub auth --project figma    # authorize and save an OAuth server to current project
kimi-mcp-hub remove --project perplexity # remove server from current project
kimi-mcp-hub add --global linear     # force global config even inside a .kimi/ project
kimi-mcp-hub sync                    # merge current project into global config
kimi-mcp-hub sync /path/to/project   # merge a specific project

--project and --global are mutually exclusive. Without either flag, commands write to the project config when a .kimi/ directory exists, and to the global config otherwise.

If you have Desktop Commander installed, you can also ask Kimi to run the command for you:

run kimi-mcp-hub add linear in the terminal

---

Profiles

Named bundles of your whole MCP-server set, independent of projects:

kimi-mcp-hub profile save work      # snapshot current global servers
kimi-mcp-hub profile load work      # replace global servers with the profile
kimi-mcp-hub profile load work --yes # skip the confirmation prompt
kimi-mcp-hub profile list           # show saved profiles
kimi-mcp-hub profile remove work

Profiles are stored as JSON in ~/.config/kimi-mcp-hub/profiles/ (platform-specific config dir). load replaces the global server set — servers not in the profile are removed from ~/.kimi-code/mcp.json.

---

Localization

The CLI speaks your language via standard gettext. Language resolution order:

1. KIMI_MCP_HUB_LANG env var (explicit override, e.g. mk, en)
2. Standard locale env vars (LANGUAGE, LC_ALL, LC_MESSAGES, LANG)
3. Fallback: English

KIMI_MCP_HUB_LANG=mk kimi-mcp-hub status   # Macedonian output

Shipped translations:

Code	Language	Coverage
mk	Македонски	Core commands (init, add, remove, list, sync, status, welcome, doctor, notify, pack, test, first-run banner)

Adding a language

1. Extract new strings after wrapping them with _() (see src/kimi_mcp_hub/i18n.py):

   xgettext -o /tmp/kimi-mcp-hub.pot --no-location src/kimi_mcp_hub/cli/*.py src/kimi_mcp_hub/_post_install.py
   

2. Create the locale: msginit -i /tmp/kimi-mcp-hub.pot -l <code> -o src/kimi_mcp_hub/locale/<code>/LC_MESSAGES/kimi-mcp-hub.po
3. Translate the msgstr entries (keep [bold]/[dim] rich tags and {placeholders} intact).
4. Compile: msgfmt -o src/kimi_mcp_hub/locale/<code>/LC_MESSAGES/kimi-mcp-hub.mo src/kimi_mcp_hub/locale/<code>/LC_MESSAGES/kimi-mcp-hub.po

Not yet translated: the per-server auth flows, repair, obsidian, memory, plugin commands, --help texts, and the skills/README content (skills are LLM prompts and stay English). Wrap them with _() and regenerate the catalog to extend coverage.

---

OAuth Auto-Browser

Like Claude Code CLI, kimi-mcp-hub automatically opens your browser for OAuth:

$ kimi-mcp-hub auth github

> Github Authorization
  Auto-browser mode (like Claude Code CLI)

  Method: Device Flow -- auto browser + code

Your verification code: ABCD-1234
Opening browser...

If browser didn't open:
1. Go to: https://github.com/login/device
2. Enter code: ABCD-1234
3. Click 'Authorize'

Waiting for you to authorize in browser...

GitHub authorized successfully!

Server	Method	Auto-browser
GitHub	Device Flow (or PAT fallback)	Yes
Jira	Official MCP OAuth or API token	Yes*
Confluence	Official MCP OAuth or API token	Yes*
Slack	Bot/User token (slack-mcp-server)	Yes
Figma	Official OAuth 2.1, PAT or custom OAuth 2.0	Yes*
Gmail	Google OAuth 2.0 or npx	Yes
Linear	Official OAuth 2.1 or API key	Yes*
Stripe	Official OAuth 2.1 or restricted API key	Yes*
GitLab	Official OAuth 2.1 or PAT	Yes*
Supabase	Official remote OAuth or access-token stdio	Yes*
Datadog	API + App keys	No (manual)

* Official remote OAuth 2.1 is initiated by Kimi CLI (kimi mcp auth <server> or /mcp-config login <server>) after you add the official remote MCP server. For Slack, run kimi-mcp-hub auth slack to start the browser-based OAuth flow.

---

CLAUDE.md Compatibility

If you are migrating from Claude Code or want Kimi to automatically read project instructions, apply the claude-compat patch:

# Interactive
kimi-mcp-hub claude-compat

# Non-interactive (useful in install scripts)
kimi-mcp-hub claude-compat --yes

This appends a block to ~/.kimi-code/AGENTS.md that tells Kimi to check for two files at the start of every session:

Priority	File	Purpose
1	CLAUDE.local.md	Local overrides — machine-specific, gitignored
2	CLAUDE.md	Project-wide instructions — committed to the repo

CLAUDE.local.md takes precedence over CLAUDE.md when they conflict.

---

All Commands

Command	Description
kimi-mcp-hub	Show welcome banner and status
kimi-mcp-hub --version	Show version
kimi-mcp-hub install	Install or update Kimi MCP Hub
kimi-mcp-hub update	Update to the latest version
kimi-mcp-hub init	Full interactive wizard
kimi-mcp-hub init --yes	Non-interactive setup with defaults
kimi-mcp-hub claude-compat	Patch AGENTS.md for CLAUDE.md auto-load
kimi-mcp-hub claude-compat --yes	Apply patch without confirmation
kimi-mcp-hub status	Version, servers, skills, memory
kimi-mcp-hub welcome	Detailed welcome banner
kimi-mcp-hub notify	Short startup notification for shell wrappers
kimi-mcp-hub add <server>	Add an MCP server
kimi-mcp-hub add obsidian	Add Obsidian vault as local memory
kimi-mcp-hub add --project <server>	Add an MCP server to the current project
kimi-mcp-hub add --global <server>	Force add to the global config inside a project
kimi-mcp-hub remove <server>	Remove an MCP server
kimi-mcp-hub remove --project <server>	Remove an MCP server from the current project
kimi-mcp-hub auth <server>	OAuth with auto-browser
kimi-mcp-hub auth --project <server>	OAuth and save to the current project
kimi-mcp-hub sync	Merge project .kimi/mcp.json into global config
kimi-mcp-hub shell-init [--install]	Shell wrapper that auto-syncs on every Kimi start
kimi-mcp-hub profile save <name>	Save current global servers as a named profile
kimi-mcp-hub profile load <name> [--yes]	Replace global servers with a profile
kimi-mcp-hub profile list	List saved profiles
kimi-mcp-hub profile remove <name>	Delete a profile
kimi-mcp-hub repair	Fix broken/outdated server configs
kimi-mcp-hub import-claude	Import from Claude Desktop
kimi-mcp-hub install-plugin <repo>	Install Claude/Codex plugin into Kimi
kimi-mcp-hub install-plugin <repo> --yes	Install plugin without confirmation
kimi-mcp-hub update-plugin <name>	Update an installed plugin
kimi-mcp-hub uninstall-plugin <name>	Remove an installed plugin and its artifacts
kimi-mcp-hub list	All servers + skills + memory
kimi-mcp-hub list-skills	All 57 available skills
kimi-mcp-hub install-skill <name>	Install a skill
kimi-mcp-hub install-skill --project <name>	Install a skill and record it in .kimi/skills.json
kimi-mcp-hub test <server>	Check if server binary/HTTP endpoint is configured
kimi-mcp-hub doctor	System health check + duplicate server detection
kimi-mcp-hub obsidian status	Show configured Obsidian vaults
kimi-mcp-hub obsidian add	Add a vault at the standard location for this OS
kimi-mcp-hub obsidian add <path>	Add an Obsidian vault at a specific path
kimi-mcp-hub obsidian auto	Create/switch to project vault in current git repo
kimi-mcp-hub obsidian list	List configured Obsidian vaults
kimi-mcp-hub obsidian remove <slug>	Remove an Obsidian vault from config
kimi-mcp-hub obsidian set-default <slug>	Set the default memory vault
kimi-mcp-hub obsidian sync-templates [--templates-dir PATH] <vault-slug>	Copy templates into a vault
kimi-mcp-hub pack [ROOT]	Pack a repository into an AI-friendly markdown file
kimi-mcp-hub pack -e '<pattern>'	Exclude glob patterns (can be repeated)
kimi-mcp-hub pack --max-size <bytes> -o <path>	Set output size budget and write to file
kimi-mcp-hub review-context	Collect the pre-PR diff context for the current branch
kimi-mcp-hub review-context --base <ref>	Compare against an explicit base branch
kimi-mcp-hub review-context --json	Same, as machine-readable JSON
kimi-mcp-hub review-context --include-uncommitted	Include work that is not committed yet
kimi-mcp-hub memory config-summary [--api-key ...] [--model ...] [--base-url ...]	Configure LLM for session summaries
kimi-mcp-hub memory add "<content>" [--category user|project|general] [--tags tag1,tag2]	Save a long-term memory
kimi-mcp-hub memory search "<query>" [--limit N] [--category ...]	Search saved memories
kimi-mcp-hub memory viewer [--port N] [--no-open]	Browse memory in a local web UI
kimi-mcp-hub memory viewer --autostart	Keep the viewer up with every Kimi session
kimi-mcp-hub memory viewer --daemon|--status|--stop	Manage the background viewer
kimi-mcp-hub memory backfill-projects [--dry-run]	Recover project attribution from Obsidian notes
kimi-mcp-hub memory context	Preview the memory block injected at session start
kimi-mcp-hub memory list [--limit N] [--category ...]	List recent memories
kimi-mcp-hub memory forget <id>	Delete a memory by ID

---

25 MCP Servers

Server	Auth	Tools	Best for
Jira	OAuth (Cloud) or API token	8	Tickets, sprints, worklogs
Linear	Official OAuth 2.1 or API key	6	Issues, projects, teams
Confluence	OAuth or API token	5	Docs, wiki, pages
GitHub	Device Flow / PAT	6	Repos, PRs, issues, code
Slack	Bot/User token (slack-mcp-server)	5	Channels, DMs, search
Obsidian	STDIO (npx) — vault path	12	Local memory, notes, knowledge base
Datadog	Official remote MCP (API + App keys)	12	Metrics, logs, monitors, APM
Figma	Official OAuth 2.1, PAT or custom OAuth	9	Designs, tokens, components
Figma Context	Figma API access token	3	Design-to-code implementation
GitLab	Official OAuth 2.1 or PAT	8	Repos, MRs, issues, CI/CD pipelines
Gmail	OAuth (npx), Chrome bridge, or Python SDK	8	Read, search, send emails
HubSpot	Private App token	9	CRM contacts, deals, companies
Stripe	Official OAuth 2.1 or restricted API key	8	Payments, customers, subscriptions, invoices
Desktop Commander	STDIO (npx/Docker)	8	Terminal commands, file ops, process management
DBHub	DSN string (read-only optional)	2	Multi-database gateway (PG, MySQL, SQLite, etc.)
Mobile MCP	STDIO (npx)	9	iOS/Android automation on simulators and real devices
Grain	Browser automation	2	Meeting transcripts
Chrome DevTools	STDIO (Node 22+ required)	10	Performance, network, screenshots, console
PostgreSQL	DSN string	6	SQL queries, schema, slow query analysis
Playwright	STDIO (Node.js)	8	Browser automation, E2E testing, screenshots
Sentry	Auth token + org	6	Error tracking, issue triage, stack traces
Context7	STDIO (npx)	4	Live library docs, version-aware API lookup
Supabase	Official remote OAuth or access-token stdio	6	Database, auth, storage, realtime, edge functions
Perplexity	API key (paid, $5 trial credit)	3	Real-time web search with AI summaries + citations
Kimi Memory	None — bundled, local SQLite	4	Searching your own cross-session memory from inside a session

---

57 Skills

Core Skills (installed by default)

Skill	Description
karpathy	Clean, simple, readable code discipline
superpowers	14 agentic workflows (plan, debug, test, deploy...)
headroom	Compress large tool outputs to save tokens
context-mode	Context window optimization and token budget
cybersecurity	Cybersecurity expert (OWASP, cloud, IR, pentest)
caveman	Ultra-compressed caveman communication mode
kimi-mcp-hub-status	Show MCP Hub version and status

Frontend Skills (installed as a stack by default)

Skill	Description
react-coder	React 19 specialist (RSC, hooks)
ts-coder	TypeScript specialist (strict, generics)
ui-engineer	UI component implementation (Tailwind, a11y)
ui-ux-pro-max	UI/UX design intelligence and design systems
vercel-react-best-practices	React/Next.js performance optimization
web-design-guidelines	Audit UI code against Vercel guidelines
agent-browser	Browser automation for web tasks and testing

Recommended external skill: hallmark -- an "anti-AI-slop" design skill (20 themes, 57 slop-test gates) that keeps generated UIs from looking generic. It complements the stack above, which focuses on correctness (a11y, tokens, guidelines, perf). Install it directly through the hub (it stays updateable via update-plugin):

kimi-mcp-hub install-plugin nutlope/hallmark

Code Quality & Review Skills

Skill	Description
code-reviewer	Quick single-agent code review
code-review	Multi-agent code review (explore/coder/plan)
surgical-refactoring	Surgical code refactoring without behavior change
tdd	Test-driven development with red-green-refactor
perf-optimization	Performance profiling and optimization
security-audit	Security review checklist
security-guidance	3-layer security scanning guidance
caveman-review	Ultra-compressed code review comments

Architecture & Design Skills

Skill	Description
api-designer	REST/GraphQL API design
backend-architect	Backend architecture and system design
backend-typescript-architect	TypeScript/Bun backend architecture
codebase-design	Design deep modules and testable interfaces
domain-modeling	Build domain models and ubiquitous language
database-expert	Database design and optimization
design-system	Design tokens, component specs, and systematic design systems
api-design	REST API design patterns

DevOps & Deployment Skills

Skill	Description
docker-pro	Docker and Kubernetes best practices
gitnexus	Code knowledge graph and blast radius
resolving-merge-conflicts	Resolve git merge/rebase conflicts
deployment-patterns	CI/CD and deployment best practices
caveman-commit	Ultra-compressed Conventional Commits messages

Language / Framework Skills

Skill	Description
python-engineer	Python specialist (FastAPI, Django, async)
laravel-engineer	Laravel specialist (Eloquent, Blade, Livewire)
php-pro	Senior PHP development (strict typing, Laravel/Symfony, PSR)
wp-plugin-development	WordPress plugin development with hooks and Settings API

Data & Migrations Skills

Skill	Description
database-migrations	Safe database migration patterns

Testing & Browser Skills

Skill	Description
playwright-best-practices	Playwright testing best practices
chrome-devtools-skill	Chrome DevTools MCP debugging and automation

Research & Automation Skills

Skill	Description
search-first	Research-before-coding workflow
regex-vs-llm-structured-text	Regex vs LLM parsing decision framework

Productivity & Meta Skills

Skill	Description
claude-compat	Auto-load CLAUDE.md and CLAUDE.local.md at session start
memory-palace	Advanced memory and context retrieval
hindsight	Memory that learns from past decisions
task-master	Task management system
ralph	Autonomous loop with stop-hooks
grill-me	Stress-test a plan or design
visual-explainer	HTML diagrams and slides
research-mode	Research-driven development
ecc	Engineering competence (perf, security, research)
skill-creator	Create and optimize agent skills
agent-automation-recommender	Recommend agent automations for codebases
find-skills	Discover and install agent skills

Integration Skills

Skill	Description
stripe-best-practices	Stripe integration best practices

---

Testing

The test suite lives in tests/ (590+ tests, runs in CI on Python 3.10-3.13):

pytest -q

• tests/test_integration.py covers end-to-end flows such as init --yes, server add, remove, and test.
• Unit tests cover config handling, project-level configs, profiles, localization, Obsidian vault management, and the plugin installer.
• tests/test_registry_sync.py guards catalog consistency: skills on disk match the registry, the plugin manifest matches the CLI, and all manifest versions stay in sync.
• CI (.github/workflows/ci.yml) runs ruff + pytest on every push and PR.

---

Architecture

+-----------------------------------------+
|         kimi-mcp-hub CLI                |
|  +---------------------------------+    |
|  |  (no args) -> welcome banner    |    |
|  |  install -> GitHub update       |    |
|  |  init -> interactive wizard     |    |
|  |  add  -> writes ~/.kimi-code/...|    |
|  |  add (in .kimi/ project) -> ./.kimi| |
|  |  sync -> merge project + global |    |
|  |  profile -> named server bundles|    |
|  |  auth -> OAuth + auto browser   |    |
|  |  repair -> fix broken configs   |    |
|  |  import-claude -> migrate config|    |
|  |  list -> pretty table of tools  |    |
|  |  status -> version + health     |    |
|  |  welcome -> full info display   |    |
|  |  notify -> startup notification |    |
|  +---------------------------------+    |
|              |                          |
|  +---------------------------------+    |
|  |  Global: ~/.kimi-code/mcp.json  |    |
|  |  Project: ./.kimi/mcp.json      |    |
|  |  Project secrets: ./.kimi/mcp.env|   |
|  |  ~/.kimi-code/skills/ (58 skills)|    |
|  |  <config-dir>/kimi-mcp-hub/     |    |
|  |    tokens.json + memory.db      |    |
|  +---------------------------------+    |
|              |                          |
|  Optional shell wrapper prints notify   |
|  on every `kimi` start                  |
|              |                          |
|         Kimi CLI reads config           |
|              |                          |
|         /mcp shows tools                |
|         Skills auto-activate            |
|         Memory persists context         |
+-----------------------------------------+

---

Security Notes

• On macOS and Linux, sensitive files (tokens.json, memory.db, and ~/.kimi-code/mcp.json) are written with chmod 600 (owner read/write only).
• Run kimi-mcp-hub doctor to detect and fix overly permissive files.
• OAuth tokens are still stored as plain JSON inside those files. This keeps the tool dependency-free, but a process running as your user can read them while Kimi CLI is active.
• By default GitHub authentication uses a public OAuth app (kimi-mcp-hub). You can supply your own GitHub/Atlassian OAuth Client ID when running kimi-mcp-hub auth <server>.

---

License

MIT