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: projscan
实测（同仓库 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.
Related MCP Servers
- Alicense-qualityAmaintenanceAn MCP server that provides AI coding agents with AST-accurate, context-budget-aware codebase querying, safety gates, and team policy integration via structured tools and a local plugin layer.Last updated7304MIT
- Alicense-qualityCmaintenanceAn MCP server that provides structure-aware code analysis (symbol trees, dependencies, docs) to reduce AI agent token consumption by up to 99%, along with Git commit intelligence.Last updatedMIT
- AlicenseAqualityDmaintenanceAn MCP server that provides a persistent sandbox for AI coding agents to explore codebases server-side, returning only compact summaries to reduce context consumption.Last updated38MIT
Related MCP Connectors
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server for AI dialogue using various LLM models via AceDataCloud
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- 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