Capsule MCP server
✓ VerifiedReduces token usage for coding agents by providing compact, source-linked context packs for large repositories.
Also known as dawitlabs/capsule, capsulectx
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.3
- Last commit
- Jul 3, 2026
- License
- MIT
What is Capsule MCP?
Capsule reduces token usage for coding agents by providing compact, source-linked context packs for large repositories.
Summary generated from the project's README
About Capsule MCP server
Capsule provides compact, source-linked context packs designed to reduce token usage for coding agents working in large repositories. By scanning a project and creating Markdown files in a .capsules directory, it helps agents avoid repeatedly rediscovering the same files, architectural decisions, and setup details. This approach targets a 50–70% reduction in repeated repository-discovery context during multi-session work.
Developers can run the tool locally using npx capsulectx init or install it globally via npm, pnpm, yarn, or bun. The system can optionally enrich capsules using an installed Claude CLI, API keys, or prompts for browser-based AI. For native integration, the capsule MCP server allows agents like Claude Code to automatically discover and consume these context packs through tools such as capsule_list, capsule_get, and capsule_stale.
This tool is language-agnostic and supports monorepos like Turborepo and pnpm workspaces. It includes features for detecting stale files, estimating token savings using the cl100k_base tokenizer, and running CI-friendly freshness checks with the capsule check command.
What you can do with it
- 1Reduce agent token consumptionAn AI agent can use these context packs to avoid burning tokens on redundant repository discovery.
Written from the project's README. Every use case is checked against a quote from it.
How to install Capsule MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Capsule MCP in Claude Code
$ claude mcp add capsule -- npx -y capsulectxInstall Capsule MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"capsule": {
"command": "npx",
"args": [
"-y",
"capsulectx"
]
}
}
}Install Capsule MCP in VS Code
.vscode/mcp.json
{
"servers": {
"capsule": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"capsulectx"
]
}
}
}Install Capsule MCP in VS Code CLI
$ code --add-mcp '{"name":"capsule","type":"stdio","command":"npx","args":["-y","capsulectx"]}'Install Capsule MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"capsule": {
"command": "npx",
"args": [
"-y",
"capsulectx"
]
}
}
}Install Capsule MCP in Codex
$ codex mcp add capsule -- npx -y capsulectxInstall Capsule MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.capsule] command = "npx" args = ["-y", "capsulectx"]
Install Capsule MCP in Gemini CLI
$ gemini mcp add -s user capsule npx -- -y capsulectxInstall Capsule MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"capsule": {
"command": "npx",
"args": [
"-y",
"capsulectx"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledawitlabs/capsule is public and reachablegithub.com/dawitlabs/capsule ↗Pass
- Package names this repository as its sourcecapsulectx names dawitlabs/capsule as sourcenpmjs.com/package/capsulectx ↗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-07-03github.com/dawitlabs/capsule ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from capsulectxPass
- No critical advisory in the package or its dependencies120 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCapsule
Compact, source-linked context packs for coding agents.
Docs · Quickstart · Commands
MCP gives agents tools. Skills give agents procedures. Capsules give agents compact project context.
Large repositories make coding agents burn tokens rediscovering the same files, decisions, conventions, and setup details over and over. Capsule targets a 50–70% reduction in repeated repository-discovery context for large, multi-session agent work.
Install
No install required — run directly with npx (always gets the latest version):
npx capsulectx init
Or install globally with your package manager:
# npm
npm install -g capsulectx
# pnpm
pnpm add -g capsulectx
# yarn
yarn global add capsulectx
# bun
bun add -g capsulectx
Keep it up to date:
npm install -g capsulectx --prefer-online
Tip:
npxis the easiest option — it always runs the latest published version with no manual update step.
Quickstart
npx capsulectx init
Capsule scans your repo, optionally enriches capsules with AI (using your installed Claude CLI, API keys, or a generated prompt for any browser-based AI), and creates:
.capsules/
index.md
architecture.md
setup.md
api.md
data.md
ui.md
testing.md
deployment.md
Each capsule is a Markdown file with source fingerprints in JSON frontmatter:
---json
{
"name": "api",
"sources": ["src/api/**"],
"fingerprints": { "src/api/users.ts": "sha256:..." },
"updated_at": "2026-06-20T14:00:00.000Z"
}
---
# API Capsule
## Purpose
Request handlers, routes, controllers, and service boundaries.
## Key Files
- `src/api/users.ts`: source file matched by this capsule.
## Decisions
- Record stable decisions here so future agents do not rediscover them.
Agents read .capsules/index.md, choose the relevant capsule, check staleness, then inspect only the source files that actually matter.
Commands
| Command | What it does |
|---|---|
capsule init |
Scan repo, run AI enrichment (optional), write all capsules |
capsule enrich |
Re-run AI enrichment on existing capsules |
capsule apply |
Apply AI-generated JSON to capsule Conventions and Decisions |
capsule write <name> |
Refresh one capsule from source (preserves your edits) |
capsule refresh <name> |
Explicitly refresh one capsule |
capsule refresh --all |
Explicitly refresh all detected capsules |
capsule get <name> |
Print one capsule to stdout |
capsule scan |
Print detected source groups without writing |
capsule stale [name] |
Check which source files changed since last write |
capsule estimate <name> |
Show estimated token savings for one capsule |
capsule stats |
Show token savings across all capsules |
capsule report [name] |
Show reproducible source/capsule/stale token savings |
capsule report --write |
Write .capsules/report.md as a proof artifact |
capsule check |
CI-friendly freshness/config check; exits nonzero on stale or missing capsules |
capsule --mcp |
Start MCP server for native agent integration |
MCP Server
Capsule ships an MCP server so Claude Code and other MCP-compatible agents can natively discover and consume capsules — no manual file reads needed.
Add to your project's .claude/settings.json:
{
"mcpServers": {
"capsule": {
"command": "npx",
"args": ["capsulectx", "--mcp"]
}
}
}
Or globally in ~/.claude/settings.json to enable for all projects.
Once configured, agents get these tools automatically:
| Tool | What it does |
|---|---|
capsule_list |
List all capsules with freshness status |
capsule_get |
Read a capsule's compressed context; warns when stale but does not write |
capsule_refresh |
Explicitly refresh one capsule or all capsules |
capsule_stale |
Check which capsules have outdated sources |
capsule_stats |
Show token savings per capsule |
capsule_report |
Show machine-readable discovery-savings proof |
capsule_check |
CI-style stale/missing/config check |
capsule_init |
Generate capsules for the current repo |
Capsules are also available as MCP resources at capsule:///index and capsule:///{name}.
Seeing the savings
$ capsule report architecture
Capsule: architecture
capsule status source capsule stale saved
architecture fresh 9,607 417 0 96%
Token counts use the cl100k_base tokenizer for accurate measurement.
For CI, run:
npx capsulectx check
It exits nonzero when capsules are stale, missing, or blocked by invalid config.
Agent Workflow
Add this to AGENTS.md, CLAUDE.md, Cursor rules, or your agent instructions:
Before working in this repo:
1. Read `.capsules/index.md` if it exists.
2. Read the capsule matching the task area.
3. Run `capsule stale <name>` when the CLI is available.
4. If stale, inspect changed source files before editing.
5. Update capsules when durable project knowledge changes.
Works with any agent that can read files — Claude Code, Codex, Cursor, Windsurf, Devin, custom MCP agents.
Custom Groups
Capsule detects standard layouts out of the box. For non-standard structure, add .capsules/config.json:
{
"groups": [
{
"name": "workers",
"description": "Background jobs, queues, and scheduled tasks.",
"sources": ["src/workers/**", "src/jobs/**"]
}
],
"ignore": ["legacy/**"]
}
A groups entry with the same name as a default group overrides it. New names are appended. ignore patterns extend the default ignore list.
See docs/capsule-format.md for the public capsule file format.
Building the Demo
The animation in this README is a generated GIF — no screen-recording tools required.
npm run demo
Requires rsvg-convert (librsvg / librsvg2-tools) and ffmpeg. The script outputs docs/demo.gif from SVG frames rendered at 2× for retina. See scripts/build-demo.mjs.
Documentation Site
The OSS docs live in docs-site/ and are built with VitePress.
npm run docs:dev
npm run docs:build
Status
Capsule is early but functional. Current capabilities:
- Language-agnostic repo scanning with monorepo support (Turborepo, pnpm workspaces)
- Static analysis: framework detection, table/model extraction, route detection, env vars
- AI enrichment on init — launches your installed Claude CLI, calls Claude/OpenAI API, or generates a prompt for any browser-based AI (Claude.ai, ChatGPT, Cursor, Windsurf)
- Write-safe re-generation: human edits to Conventions and Decisions are preserved on refresh
- MCP server for native Claude Code / agent integration
- Real token counting (cl100k_base) with savings dashboard
- TypeScript API surface extraction
- Binary file filtering
- Stale detection and token savings estimation
- Reproducible
reportand CI-friendlycheck - Custom group config via
.capsules/config.json - Auto-patches
CLAUDE.md,AGENTS.md,.cursorrules,.windsurfruleswith capsule instructions
Roadmap:
- smarter
writethat diffs source changes and suggests targeted updates - before/after token reports for real agent sessions
- GitHub Action wrapper for
capsule check
Install for Local Development
git clone https://github.com/dawitlabs/capsule.git
cd capsule
npm install
npm run build
node dist/cli.js init
License
MIT
Capsule MCP questions
How do I add Capsule MCP to Claude Code?
Run claude mcp add capsule -- npx -y capsulectx in your terminal. Add --scope user to make it available in every project.
How do I add Capsule MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Capsule reduce token waste?
It creates compact context packs that allow agents to inspect only relevant source files instead of rediscovering the entire repository.
Can I use Capsule with my existing AI tools?
Yes, it works with any agent that can read files, including Claude Code, Cursor, Windsurf, and Devin.