Kuma MCP server
Commit Oct 21, 2026Provides a safety and orchestration layer for AI coding agents by injecting project context, decision memory, and impact analysis before code modifications.
Also known as plumpslabs/kuma, @plumpslabs/kuma
- Stars
- 2
- Tools
- 6
- Downloads, 30 days
- β
- Latest version
- β
- Last commit
- Oct 21, 2026
- License
- MIT
What is Kuma MCP?
Kuma provides a safety and orchestration layer for AI coding agents by injecting project context, decision memory, and impact analysis before code modifications. It exposes 6 tools, such as kuma_context, kuma_kuma_context, kuma_memory.
Summary generated from the project's README
About Kuma MCP server
Kuma serves as a safety and orchestration layer designed for AI coding agents like Claude Code, Cursor, and Windsurf. It functions as a pre-modification research pipeline that injects project context and decision memory into the agent's workflow. By acting as a shadow memory, it helps prevent agents from breaking dependencies or repeating past mistakes during code edits.
The server operates locally and stores all project context within a .kuma directory using a SQLite-based knowledge graph. It provides three primary tools: kuma_context for research and mapping, kuma_memory for recording decisions and architectural flows, and kuma_safety for monitoring anti-patterns and managing checkpoints. Developers can also use Kuma Studio, a web dashboard running on localhost:3322, to visualize the knowledge graph and manage recorded gotchas.
Setup is straightforward via npm or npx, and it integrates with MCP-compatible clients through standard configuration. The system uses a 5-step research pipeline to analyze impact and history before any code is touched, ensuring the agent understands the blast radius of its proposed changes.
What you can do with it
- 1Analyze code change impactAsk the agent to perform a blast radius analysis to see how a modification affects the rest of the codebase.
- 2Prevent recurring bugsInstruct the agent to record a specific quirk or bug as a gotcha to prevent it from making the same mistake in future sessions.
- 3Preserve architectural decisionsHave the agent document the rationale behind a specific implementation choice using ADR-style tracking.
- 4Revert risky refactorsUse the checkpoint system to create a snapshot before a major change so you can restore the state if things go wrong.
Written from the project's README. Every use case is checked against a quote from it.
How to install Kuma MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Kuma MCP in Claude Code
$ claude mcp add kuma -- npx -y @plumpslabs/kumaInstall Kuma MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"kuma": {
"command": "npx",
"args": [
"-y",
"@plumpslabs/kuma"
]
}
}
}Install Kuma MCP in VS Code
.vscode/mcp.json
{
"servers": {
"kuma": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@plumpslabs/kuma"
]
}
}
}Install Kuma MCP in VS Code CLI
$ code --add-mcp '{"name":"kuma","type":"stdio","command":"npx","args":["-y","@plumpslabs/kuma"]}'Install Kuma MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"kuma": {
"command": "npx",
"args": [
"-y",
"@plumpslabs/kuma"
]
}
}
}Install Kuma MCP in Codex
$ codex mcp add kuma -- npx -y @plumpslabs/kumaInstall Kuma MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.kuma] command = "npx" args = ["-y", "@plumpslabs/kuma"]
Install Kuma MCP in Gemini CLI
$ gemini mcp add -s user kuma npx -- -y @plumpslabs/kumaInstall Kuma MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"kuma": {
"command": "npx",
"args": [
"-y",
"@plumpslabs/kuma"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @plumpslabs/kuma 2.4.25 in an isolated container with no network and no keys. It answered and listed 6 tools.
Kuma MCP tools 6
Read from the server with tools/listkuma_contextContext & memory recall. Call FIRST each session. Lean β each call returns only what you need. CORE ACTIONS (use these): `init` (start of session: project brief + session state), `research` (before editing unfamiliar code), `history` (why is this file written this way), `flow` (read a recorded architecture flow), `map` (repository topology), `impact` (blast radius analysis), `cluster` (concept-level subsystem nodes), `skeleton` (compressed AST outline omitting bodies), `reuse` (discover existing helpers before writing duplicate code).
kuma_kuma_contextContext & memory recall. Call FIRST each session. Lean β each call returns only what you need. CORE ACTIONS (use these): `init` (start of session: project brief + session state), `research` (before editing unfamiliar code), `history` (why is this file written this way), `flow` (read a recorded architecture flow), `map` (repository topology), `impact` (blast radius analysis), `cluster` (concept-level subsystem nodes), `skeleton` (compressed AST outline omitting bodies), `reuse` (discover existing helpers before writing duplicate code).
kuma_memoryPersistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components). CORE ACTIONS (use these): `gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph), `gotcha_resolve` (archive fixed bugs), `test_outcome` (record changed files + failed tests to train test selection).
kuma_kuma_memoryPersistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components). CORE ACTIONS (use these): `gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph), `gotcha_resolve` (archive fixed bugs), `test_outcome` (record changed files + failed tests to train test selection).
kuma_safetySafety & verification. Use at task boundaries, not on every edit. CORE ACTIONS (use these): `guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after), `cost` (cost-per-tool ledger).
kuma_kuma_safetySafety & verification. Use at task boundaries, not on every edit. CORE ACTIONS (use these): `guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after), `cost` (cost-per-tool ledger).
Automated checks
Ran Nov 14, 2026Full report βNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work Β· What to fix for more points
- Source repository linked and reachableplumpslabs/kuma is public and reachablegithub.com/plumpslabs/kuma βPass
- Package names this repository as its source@plumpslabs/kuma names plumpslabs/kuma as sourcenpmjs.com/package/@plumpslabs/kuma βPass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html βPass
- Commit or release in the last yearLast commit or release 2026-10-21github.com/plumpslabs/kuma βPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @plumpslabs/kumaPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model18 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSafety-first context & orchestration engine for AI coding agents.
Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, Zed, and more.
What is Kuma?
Kuma is an MCP (Model Context Protocol) server that acts as a pre-modification safety layer for AI coding agents. Before an agent touches your code, Kuma enforces a research and safety pipeline β like a pre-flight checklist for code changes.
The Problem: AI agents often modify code without understanding the full context β missing dependencies, breaking related features, or repeating past mistakes.
The Solution: Kuma is a shadow memory that injects "where is this file fragile and why is it written this way" right before the agent touches it:
- πͺ Auto-inject hooks β gotchas/decisions/history injected before every edit, zero extra steps
- π§ Knowledge graph β SQLite-based derived cache (hash-verified, never stale)
- π Decision memory β ADR-style decision tracking across sessions
- π Kuma Studio β Visual dashboard for gotchas, decisions, and shadow-memory metrics
Quick Start
β‘ Universal 1-Liner (Auto-detects your IDE/Agent)
curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash
π§© Or Install as a Native Plugin
- Claude Code Marketplace:
/plugin marketplace add plumpslabs/kuma /plugin install kuma@plumpslabs-kuma - Antigravity CLI (AGY):
agy plugin add https://github.com/plumpslabs/kuma - Via NPX (Zero Install):
npx @plumpslabs/kuma init --all
π See INSTALL.md for the complete provider matrix (Cursor, Windsurf, OpenCode, Copilot, Zed, Cline, Aider, etc.).
Core Architecture: 3 Pipeline-Driven Tools
Kuma exposes 3 coarse-grained tools with 15 core actions β the full agent surface. Anything else (impact, navigate, changes, digest, drift, resume, mine, session, delete_node, clear, goal_progress, check, audit, security, gc, ast, validate, gotcha_staleness) was removed β not hidden, gone β so the agent never has to choose from 30+ options and there is no dead surface to maintain.
π§ kuma_context β Context & Research
| Action | Purpose | Impact |
|---|---|---|
init |
Lean project brief + restore session + branch tracking | π΄ Required first |
research |
5-step pipeline: cache β graph β scan β impact β decision | π΄ Required before edits |
map |
Monorepo package topology & workspace boundary mapping | π΄ High |
cluster |
Concept-level subsystem clusters with typed relationship verbs | π΄ High |
skeleton |
Compressed AST code outline (85-93% token reduction) | π΄ High |
reuse |
Anti-duplication helper discovery before writing new code | π΄ High |
impact |
Blast radius analysis with PageRank centrality scoring | π΄ High |
history |
Why is this file written this way (cross-session trace) | π΄ High |
flow |
Read a recorded architecture flow | π΄ High |
πΎ kuma_memory β Decision & Knowledge
| Action | Purpose | Impact |
|---|---|---|
gotcha |
Record bugs/quirks + lifecycle (active β resolved β deprecated) |
π΄ Exponential |
arch_flow |
Record architecture flow (max 5 core files) | π΄ Exponential |
decision |
Record ADR-style decision with rationale | π΄ Exponential |
research_save |
Save research findings to cache | π‘ Linear |
search |
Quick lookup of memory + knowledge graph | π‘ Linear |
π‘οΈ kuma_safety β Safety & Verification
| Action | Purpose | Impact |
|---|---|---|
guard |
Detect anti-patterns, drift, runaway loops | π΄ Required |
verify |
Post-edit blast radius & affected test targeting (<50ms static resolution) | π΄ High |
checkpoint |
Labeled snapshot before risky work | π‘ Linear |
rollback_label |
Restore a labeled snapshot | π‘ Linear |
Architecture
Kuma exposes exactly 3 coarse-grained tools β the agent picks an action, Kuma runs the internal workflow:
| Tool | Core Actions | Purpose |
|---|---|---|
kuma_context |
init, research, map, cluster, skeleton, reuse, impact, history, flow |
Load project context, understand unfamiliar code |
kuma_memory |
gotcha, decision, arch_flow, research_save, search |
Persistent knowledge that saves future sessions |
kuma_safety |
guard, verify, checkpoint, rollback_label |
Pre-risk guard, post-edit blast radius verification, snapshot/restore |
Everything else is an internal action β not exposed to the agent. The agent uses its own native tools for editing, searching, and execution β Kuma is memory & safety, not a code manager.
What Kuma Provides
- Knowledge Graph β SQLite + FTS5 full-text search (derived cache)
- Session Memory β track tool calls, recordings, and efficiency per session
- Guard System β real-time monitoring with blocking warnings for anti-patterns
- Shadow Injection β gotchas injected before edits via hooks (zero token waste when clean)
- Kuma Studio β visual dashboard with graph, gotchas, and injection metrics
- Checkpoint/Rollback β atomic snapshots before major refactors
Kuma Studio
Kuma Studio is a streamlined, modular web dashboard for visualizing your codebase intelligence, gotchas shield, and workspace topology without visual clutter.
Features
- π‘οΈ Gotcha Shield β Filter gotchas by status (
active,verified,resolved), severity, and copy workarounds in 1 click - π Domain Sequence Flows β Linear architecture hops and execution sequences
- π¦ Workspace & Blast Radius β Monorepo package dependency matrix and real-time blast radius impact simulator
- β‘ Health & Efficiency β Session metrics, estimated hours saved, verification pass rates, and injection statistics
- πΈοΈ Calm Knowledge Graph β Clean node-link visualization with optional physics simulation and depth controls
Usage
# Start Kuma Studio
kuma studio
# Or via npx
npx -y @plumpslabs/kuma studio
Studio runs at http://localhost:3322 and provides:
- Real-time graph visualization
- Copy report functionality for activity analysis
- Node detail modals with relations and gotchas
- Search and filter capabilities
- Physics-based graph layout with depth controls
Knowledge Graph Schema
Kuma builds a comprehensive knowledge graph with these node types:
| Node Type | Description |
|---|---|
feature |
High-level module (e.g., Auth, Billing) |
arch_flow |
Architecture flow between files |
gotcha |
Known bug or quirk |
decision |
ADR-style decision with rationale |
function |
Function or method |
class |
Class definition |
component |
UI component |
file |
Source file |
api_route |
API endpoint |
test |
Test file |
research |
Research cache entry |
Edge types include: contains, flows_through, owns, explains.
Safety Layer
Audit Trail
Every safety check is logged to the audit trail:
- Tool name and parameters
- Risk level (low/medium/high/critical)
- Allowed/blocked decision
- Duration and metadata
Workflow
A typical Kuma-powered session follows this flow:
1. INIT β kuma_context({ action: 'init' })
Load project brief, restore session context
2. RESEARCH β kuma_context({ action: 'research', scope: '<area>' })
5-step pipeline: cache β graph β impact β decision β safety
3. GUARD β kuma_safety({ action: 'guard' })
Check for anti-patterns, drift, runaway loops
4. EDIT β Agent modifies code (native tools)
5. RECORD β kuma_memory({ action: 'gotcha' | 'arch_flow' | 'decision' })
Record what was learned for future sessions
6. VERIFY β kuma_safety({ action: 'verify' })
Auto-run scoped tests + validation
7. CHECKPOINT β kuma_safety({ action: 'checkpoint', label: 'post-<feature>' })
Snapshot once stable β restore with rollback_label if needed
Per-Project Context Model
Kuma stores all context locally in .kuma/:
.kuma/
βββ kuma.db # SQLite knowledge graph (WASM) β nodes, edges, research cache, changes
βββ init.md # Project behavioral rules (generated by `kuma init`)
βββ memory.json # Session state + metrics (auto)
βββ auto-gotcha.json # Self-learning loop state (auto)
βββ policy.yml # OPTIONAL safety policy β only read if you create it
βββ memories/ # Decision log markdown (decisions.md)
βββ checkpoints/ # Atomic snapshots (label/ with kuma.db + files/)
Hooks are registered in
.claude/settings.json(PreToolUse) β not stored under.kuma/.
Research cache is not a folder β it lives in the
research_cachetable insidekuma.db.
Key principle: Context is per-project, per-agent. No shared state between projects.
Why Kuma?
| Problem | Without Kuma | With Kuma |
|---|---|---|
| Context | Agent forgets project-specific patterns | Knowledge graph persists across sessions |
| Safety | Agent may break critical code | Policy engine blocks risky operations |
| Impact | Agent doesn't know what's affected | Impact analysis traces dependencies |
| Coordination | Multiple agents conflict | Per-agent session state + audit trail avoid collisions |
| Memory | Agent repeats past mistakes | Decision memory + gotchas prevent loops |
| Reversibility | Hard to undo changes | Checkpoint snapshots + rollback_label |
| Staleness | Knowledge becomes outdated | Drift detection + gotcha staleness checks flag stale data |
Installation
# Global install
npm install -g @plumpslabs/kuma
# Or use npx (no install needed)
npx -y @plumpslabs/kuma
# With pnpm
pnpm add -g @plumpslabs/kuma
Requirements
- Node.js >= 18.0.0
- No native dependencies (uses WASM for SQLite)
CLI Commands
# Start MCP server (default)
kuma
# Start Kuma Studio dashboard
kuma studio
# Initialize a project
kuma init
# Show version
kuma --version
# Show help
kuma --help
Configuration
MCP Client Configuration
Add to your MCP client config (e.g., Claude Desktop):
{
"mcpServers": {
"kuma": {
"command": "npx",
"args": ["-y", "@plumpslabs/kuma"]
}
}
}
Environment Variables
| Variable | Description | Default |
|---|---|---|
KUMA_DB_PATH |
Custom database path | .kuma/kuma.db |
KUMA_POLICY_PATH |
Custom policy file | .kuma/policy.yml |
KUMA_STUDIO_PORT |
Studio server port | 3322 |
Development
# Clone the repo
git clone https://github.com/plumpslabs/kuma.git
cd kuma
# Install dependencies
pnpm install
# Build
pnpm run build:all
# Run tests
pnpm test
# Start studio in dev mode
pnpm run studio:dev
Power Curve: What to Record
| What to Record | When | Why | Impact |
|---|---|---|---|
arch_flow |
After tracing a complete flow | Saves 5-10 files next session | π΄ Exponential |
gotcha |
IMMEDIATELY when finding bugs | Prevents re-discovery | π΄ Exponential |
decision |
When choosing between options | Preserves rationale | π΄ Exponential |
feature |
When identifying a module | Creates owns edges to files | π΄ Exponential |
research_save |
After exploring an area | Creates search cache | π΄ Exponential |
| Function/class nodes | Skip | Agent can grep/glob | π’ Skip |
| Import edges | Skip | Agent can read imports | π’ Skip |
| Visual graph | Skip | For humans, not AI | π’ Skip |
License
MIT β use freely in personal and commercial projects.
Community
- GitHub: github.com/plumpslabs/kuma
- Issues: github.com/plumpslabs/kuma/issues
- npm: npm.im/@plumpslabs/kuma
Kuma MCP questions
How do I add Kuma MCP to Claude Code?
Run claude mcp add kuma -- npx -y @plumpslabs/kuma in your terminal. Add --scope user to make it available in every project.
How do I add Kuma MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Kuma MCP provide?
It exposes 6 tools, including kuma_context, kuma_kuma_context, kuma_memory, kuma_kuma_memory, kuma_safety.
What is Kuma?
Kuma is an MCP server that acts as a pre-modification safety layer for AI coding agents, enforcing a research and safety pipeline before code is changed.
Which AI agents are compatible with Kuma?
Kuma works with any MCP-compatible agent, including Claude Code, Cursor, Windsurf, Zed, GitHub Copilot, and more.
Does Kuma manage my code edits?
No, Kuma provides memory and safety context; the agent uses its own native tools for editing, searching, and execution.
How can I visualize the codebase intelligence?
You can use Kuma Studio, a modular web dashboard that provides visual representations of the knowledge graph, workspace topology, and session metrics.