MCP CLI Scripts Pattern 是一套与 MCP 服务器配套的 CLI 脚本模式，状态为生产就绪，最后更新于 2026-01-09。其核心思路是：在构建 MCP 服务器时，同时创建配套的 CLI 脚本，为 Claude Code 等终端环境提供相同甚至更丰富的功能。
一、用途 远程 MCP（Claude.ai）的结果会流经模型上下文窗口，无文件系统访问，每次只能进行单次调用，无状态且不能缓存，输出通常为 JSON 交给模型，链式调用由模型编排。而 CLI 脚本（Claude Code）的结果保留在本地、只共享相关部分，拥有完整读写权限，可按文件批量处理输入，能本地缓存结果，输出可为 JSON、CSV、表格、文件或 stdout，并可直接进行管道与链式调用。该模式即用于此类终端场景。
二、主要能力（设计原则）
- 每个工具对应一个脚本：每个脚本做好一件事，与 MCP 工具对应但具备扩展能力。
- 默认输出 JSON：脚本默认将 JSON 输出到 stdout，便于 Claude Code 读取和解析。例如 console.log(JSON.stringify({ success: true, data: result }, null, 2))；除非请求 --format text，否则避免非结构化文本。
- 为本地使用扩展能力：提供远程 MCP 中不常见的功能，包括输入输出文件（--input、--output、--append）、缓存（--cache、--cache-ttl 3600、--no-cache）、输出格式（--format json|csv|table、--quiet、--verbose）、批量操作（--batch、--concurrency 5）。
- 一致的参数模式：统一使用 --input、--output、--format、--profile、--verbose、--help 等参数。
- 使用 shebang 直接执行：脚本应可直接运行。
关键规则方面，应始终使用 #!/usr/bin/env npx tsx 作为 shebang（而非 node 或 ts-node），默认将 JSON 输出到 stdout，跨脚本采用一致的参数模式，在 SCRIPTS.md 中记录脚本，并用结构化 JSON 处理错误，如 { success: false, error: "..." }。不应使用 console.log() 输出散文式文本，不应每个脚本采用不同参数模式，不应忘记在 SCRIPTS.md 中记录脚本，也不应在 shebang 中使用 node 或 ts-node（tsx 可处理 ESM 与 TypeScript）。
三、目录结构与使用方式 推荐目录结构为：mcp-{name}/ 下包含 src/index.ts（给 Claude.ai、远程客户端用的 MCP 服务器）、scripts/ 下每个工具一个脚本以及可选的 _shared.ts（共享认证/配置辅助）、SCRIPTS.md（为 Claude Code 记录可用脚本）、package.json 和 README.md。
脚本模板位于 templates/。script-template.ts 是完整的 TypeScript 脚本模板，包含参数解析、JSON 输出和文件 I/O 模式，可通过 cp ~/.claude/skills/mcp-cli-scripts/templates/script-template.ts scripts/new-tool.ts 复制到项目。SCRIPTS-TEMPLATE.md 用于记录 MCP 服务器仓库中的可用脚本，可通过 cp 复制为 SCRIPTS.md。规则文件 rules/mcp-cli-scripts.md 可复制到项目的 .claude/rules/ 中。
若希望在 MCP 与脚本之间共享逻辑，可抽取核心模块：src/core/ 存放纯函数（无 I/O 假设），src/mcp/ 的处理器从 core 导入，src/cli/ 的 CLI 包装器也从 core 导入。当然，保持两者独立也可以，脚本可能演化出 MCP 不支持的能力。
依赖方面，需要 tsx@4.21.0（无需编译即可执行 TypeScript），在 package.json 的 devDependencies 中添加 "tsx": "^4.21.0"。
四、适用场景 适合在终端/Claude Code 环境中工作、需要将结果保存到文件、从文件批量处理输入、串联多个操作、需要缓存以重复查询、想要更丰富输出格式等情况。而在 Claude.ai 网页界面、简单的一次性查询、无需文件 I/O、构建对话流程时，应使用 MCP 工具。
五、限制与注意事项 该资料未提供收费、价格、平台或效果的说明。使用时需遵循上述“应做”与“不应做”的规则，并确保在 SCRIPTS.md 中记录每个脚本，使用 tsx 而非 node 或 ts-node 作为 shebang。