How do I use ctxshot-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ctxshot-mcp create 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

npm MCP node license

给 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 调 `session_brief` → `@.ai/context.md`
想知道简报多大	跑完再看	`context_stats` 先看 token 估算
临时要结构	复制终端输出	`pack_context` 直接返回 Markdown
要读全库	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:mcp

MCP Tools 完整说明

`session_brief`（推荐：每日起手）

打包 compact + diff 简报，写入 .ai/context.md，并返回全文。

参数	类型	说明
`root`	string?	项目根目录（默认：server cwd）
`out`	string?	输出路径，相对 root（默认 `.ai/context.md`）

典型用法： 新会话开头让 Agent 调用，然后 @.ai/context.md。

`pack_context`

返回 Markdown 简报，不写文件。

参数	类型	默认	说明
`compact`	boolean?	`true`	浅树 + 截断 README
`diff`	boolean?	`false`	包含 git 摘要
`depth`	number?	compact=2	目录树深度 (1–6)
`maxEntries`	number?	compact=50	最多树节点 (10–500)
`root`	string?	cwd	项目根目录

`context_stats`

只返回 JSON 统计，不拉全文。适合对比 token 成本。

参数	类型	说明
`compact`	boolean?	同 pack_context
`diff`	boolean?	同 pack_context
`root`	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."
}

架构

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
核心	`packContext()`	同左
输出	stdout 或 `-o` 文件	Tool 返回 + `session_brief` 写文件

和 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 导出。

License

MIT · ctxshot CLI · npm

Install Server

A

license - permissive license

A

quality

B

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

项目	链接
ctxshot CLI	https://github.com/G12789/ctxshot
evaldrift	https://github.com/G12789/evaldrift
mcp-quickstart	https://github.com/G12789/mcp-quickstart
ship-skills	https://www.npmjs.com/package/ship-skills

ctxshot-mcp

ctxshot-mcp

解决什么问题

实测（同仓库 benchmark）

30 秒接入

Cursor

Claude Code

验证

MCP Tools 完整说明

`session_brief`（推荐：每日起手）

`pack_context`

`context_stats`

推荐工作流

架构

和 Repomix 怎么选

常见问题

开发

相关项目

License

Maintenance

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

ctxshot-mcp

解决什么问题

实测（同仓库 benchmark）

30 秒接入

Cursor

Claude Code

验证

MCP Tools 完整说明

session_brief（推荐：每日起手）

pack_context

context_stats

推荐工作流

架构

和 Repomix 怎么选

常见问题

开发

相关项目

License

Maintenance

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`session_brief`（推荐：每日起手）

`pack_context`

`context_stats`