ctxshot-mcp
ctxshot-mcp is a lightweight MCP server that generates compact project context briefs for AI coding sessions, helping you avoid manually pasting project info at the start of each conversation. It runs fully offline — no network calls, no data uploaded — and is significantly lighter than Repomix (~200–2k tokens vs potentially 100k+).
session_brief– Generates a compact project brief (directory tree, npm scripts, README/AGENTS excerpt, git diff summary) and automatically writes it to.ai/context.md. Ideal for kicking off a new AI coding session or switching tasks.pack_context– Returns a lightweight Markdown project brief directly without writing a file. Supports options for tree depth (depth), max tree entries (maxEntries), compact mode (compact), and whether to include git diff/commits (diff).context_stats– Returns a JSON summary of estimated token cost, line count, tree size, and other metadata without generating the full Markdown — useful for estimating token costs before committing to a full pack.
It integrates with AI development environments like Cursor and Claude Code, enabling agents to understand project structure efficiently without reading the entire repository.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ctxshot-mcpcreate a project briefing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ctxshot-mcp
⭐ 推荐：
npx ship-skills init（已登录gh会自动支持作者）
给 Cursor / Claude Code 的轻量项目简报 MCP。 每天开会话 ~400 token 交代项目结构，不是 Repomix 全库打包。
Tools:
session_brief·pack_context·context_stats
ctxshot 的 MCP 封装。让 Agent 原生调用打包逻辑，自动写 .ai/context.md，不用你每次手动 npx ctxshot。
解决什么问题
场景 | 笨办法 | ctxshot-mcp |
每天新开会话 | 反复贴 README、glob 目录 | Agent 调 |
想知道简报多大 | 跑完再看 |
|
临时要结构 | 复制终端输出 |
|
要读全库 | Repomix 一把梭 | 仍用 Repomix，本 MCP 不替代 |
Related MCP server: MCP Plus
实测（同仓库 benchmark）
基于 ctxshot 自身仓库：
工具 | 耗时 | 估 token |
ctxshot / session_brief | 356ms | 423 |
README 手贴 | <1ms | 685 |
repomix --stdout | 3.6s | 7,023 |
30 秒接入
Cursor
~/.cursor/mcp.json 或项目 .cursor/mcp.json：
{
"mcpServers": {
"ctxshot": {
"type": "stdio",
"command": "npx",
"args": ["-y", "ctxshot-mcp@latest"]
}
}
}Developer: Reload Window 后，Settings → Tools & MCPs 看到绿色 ctxshot 即成功。
Claude Code
claude mcp add ctxshot -- npx -y ctxshot-mcp@latest验证
npx ctxshot-mcp # stdio server（由 IDE 拉起，勿手动交互）或在项目里：
git clone https://github.com/G12789/ctxshot-mcp
cd ctxshot-mcp && npm install
npm run test:mcpMCP Tools 完整说明
session_brief（推荐：每日起手）
打包 compact + diff 简报，写入 .ai/context.md，并返回全文。
参数 | 类型 | 说明 |
| string? | 项目根目录（默认：server cwd） |
| string? | 输出路径，相对 root（默认 |
典型用法： 新会话开头让 Agent 调用，然后 @.ai/context.md。
pack_context
返回 Markdown 简报，不写文件。
参数 | 类型 | 默认 | 说明 |
| boolean? |
| 浅树 + 截断 README |
| boolean? |
| 包含 git 摘要 |
| number? | compact=2 | 目录树深度 (1–6) |
| number? | compact=50 | 最多树节点 (10–500) |
| string? | cwd | 项目根目录 |
context_stats
只返回 JSON 统计，不拉全文。适合对比 token 成本。
参数 | 类型 | 说明 |
| boolean? | 同 pack_context |
| boolean? | 同 pack_context |
| string? | 项目根目录 |
返回示例：
{
"estimatedTokens": 423,
"lineCount": 76,
"treeLineCount": 22,
"compact": true,
"hasGit": true,
"manifestCount": 1,
"root": "/your/project",
"hint": "Use pack_context for full brief; Repomix for entire codebase."
}推荐工作流
┌─────────────────────────────────────────────────────┐
│ 1. 打开项目（或传 root 参数） │
│ 2. 新会话 → Agent 调用 session_brief │
│ 3. 生成 .ai/context.md + ledger-events.jsonl │
│ 4. 对话 @.ai/context.md │
│ 5. 读具体实现 → @文件 或 Repomix │
└─────────────────────────────────────────────────────┘.ai/ledger-events.jsonl 记录每次调用的 token 估算，为后续 token 账本功能预埋。
架构
Cursor / Claude Code
│ stdio MCP
▼
ctxshot-mcp (本仓库)
├── index.ts stdio 入口
└── server.ts 注册 3 个 Tool
│
▼
ctxshot/core (npm 依赖)
packContext() — 与 CLI 共用同一套逻辑
│
▼
.ai/context.md
.ai/ledger-events.jsonl与 CLI 的关系：
ctxshot CLI | ctxshot-mcp | |
调用方 | 人 / 脚本 | Agent / IDE |
传输 | 终端 | MCP stdio |
核心 |
| 同左 |
输出 | stdout 或 | Tool 返回 + |
和 Repomix 怎么选
ctxshot-mcp | Repomix | |
Token | ~200–2k | 可达 100k+ |
速度 | <1s | 大仓库慢 |
内容 | 树 + 脚本 + 摘要 | 全文件内容 |
场景 | 每日开会话 | 全库 refactor / 审计 |
关系 | 互补 | 互补 |
常见问题
Q: MCP 绿灯但扫错目录？
全局 MCP 的 cwd 可能是用户主目录。解法：
把目标项目作为 Cursor 工作区根目录打开
或调用时传
root:"/path/to/your/project"
Q: 和 CLI 有什么区别？
逻辑完全一样（共用 ctxshot/core）。MCP 让 Agent 在会话里自动调用，不用你记命令。
Q: 能替代 Repomix 吗？
不能。简报 ≠ 全库。需要 AI 读每一行代码时请用 Repomix。
Q: 离线能用吗？
能。纯本地扫描，不联网，不上传任何内容。
开发
git clone https://github.com/G12789/ctxshot-mcp
cd ctxshot-mcp && npm install
npm run build
npm run test:smoke # 单元 smoke
npm run test:mcp # MCP 客户端端到端
npm run inspect # MCP Inspector依赖 ctxshot@0.2.1+ 的 ctxshot/core 导出。
相关项目
项目 | 链接 |
ctxshot CLI | |
evaldrift | |
mcp-quickstart | |
ship-skills |
License
MIT · ctxshot CLI · npm
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/G12789/ctxshot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server