MCPX 🧳

一种为大型语言模型和人类设计的高效Token MCP客户端。

为什么选择MCPX？ 其他MCP客户端会生成巨大的JSON模式，浪费Token并使人困惑。而MCPX返回的是TypeScript签名——Claude和开发者可以立即理解工具签名。使用LLM原生语法（如server.func({ args })）调用工具，通过标准输入执行批处理操作，并获得TOON输出（比JSON少90%的Token）。

MCPX帮助您充分利用Anthropic的《使用MCP进行代码执行》指导中强调的“代码执行”工作流程：发现系统上已配置的MCP服务器，直接调用它们，并在TypeScript中组合更丰富的自动化。这一切都开箱即用——无需样板代码，无需探索模式。

安装

Homebrew

# 添加Tap
brew tap AIGC-Hackers/mcpx

# 安装mcpx
brew install mcpx

# 或者一次性安装
brew install AIGC-Hackers/mcpx/mcpx

不安装运行

bunx mcpx list

备选Tap (steipete)

brew tap steipete/tap
brew install steipete/tap/mcpx

steipete Tap与MCPX 0.3.2一起发布。如果您看到旧版本，请先运行brew update再重新安装。

MCPX与其他MCP客户端对比

功能	MCPX	典型MCP客户端
模式输出	TypeScript（可读，Token高效）	JSON模式（冗长，Token密集）
调用语法	linear.createIssue({ title: "Bug" })	手动构造JSON
批处理调用	✅ 多行，标准输入，注释	❌ 一次一个调用
输出格式	TOON（Token减少90%）	原始JSON
OAuth流程	✅ 自动触发，无错误	手动或有错误
LLM准备	✅ 专为Claude/GPT工作流设计	⚠️ 需要Token预算

主要功能

• 零配置发现。 createRuntime()合并./mcp.json和~/.mcpx/mcp.json，扩展${ENV}占位符，并汇集连接，以便在多次调用中复用传输。首次运行时自动迁移Cursor/Claude/Codex/Windsurf/VS Code配置到~/.mcpx/mcp.json。
• 灵活的数据格式。 使用函数语法或结构化的JSON/JSON5/YAML/TOML数据调用工具。默认输出为TOON（适合LLM），使用--output标志可以选择原始/JSON/文本格式。
• 友好的组合API。 createServerProxy()以舒适的驼峰命名法暴露工具，自动应用JSON模式默认值，验证必需参数，并返回带有.text(), .json(), 和.content()辅助方法的CallResult。
• OAuth和标准I/O舒适性。 内置OAuth缓存、日志尾随和标准I/O包装器，让您从同一接口处理HTTP、SSE和标准I/O传输。
• 临时连接。 指向CLI的任何MCP端点（HTTP或标准I/O），无需更改配置，之后如果需要可以保存。预期浏览器登录的托管MCP（如Supabase、Vercel等）会被自动检测到，并在需要时自动触发OAuth。详情见docs/adhoc.md。

快速开始

MCPX自动发现您已在Cursor、Claude Code/Desktop、Codex或本地覆盖中配置的MCP服务器。通过Homebrew安装或使用bunx mcpx即时运行。需要完整的命令参考（标志、模式、返回类型）？查看docs/cli-reference.md。

调用MCP工具

# 函数语法 - 对代理和交互式使用自然
mcpx call 'linear.create_comment({ issueId: "ENG-123", body: "Great!" })'

# 数据格式 - 显式且结构化（也支持JSON5/YAML/TOML）
mcpx call '{ tool: "linear.create_comment", args: { issueId: "ENG-123", body: "Great!" } }'

列出您的MCP服务器

mcpx list
mcpx list context7
mcpx list https://mcp.linear.app/mcp --all-parameters
mcpx list shadcn.io/api/mcp.getComponents           # URL + 工具后缀自动解析
mcpx list --stdio "bun run ./local-server.ts" --env TOKEN=xyz

• 添加--output json以输出机器可读的摘要，包括每个服务器的状态（认证/离线/HTTP/错误计数），以及单个服务器运行时的完整工具模式负载。

现在您可以指向mcpx list的临时服务器：直接提供URL或使用新的--http-url/--stdio标志（加上--env, --cwd, --name, 或--persist）来描述任何MCP端点。直到您持久化该定义之前，您仍然需要重复相同的URL/标准I/O标志用于mcpx call——只有当您通过--persist或mcpx config add将其合并到配置中时，打印的slug才变得可重用。当服务器需要身份验证时，OAuth会自动触发。更多细节参见docs/adhoc.md。

单个服务器列表现在显示TypeScript Spec格式，因此您可以直接复制粘贴签名到mcpx call：

linear - 托管Linear MCP
  23 工具 · 1654毫秒 · HTTP https://mcp.linear.app/mcp

/**
 * 在特定的Linear问题上创建评论
 */
type CreateCommentSpec = {
  tool: 'create_comment'
  args: {
    issueId: string
    body: string
    parentId?: string
    notifySubscribers?: boolean
    labelIds?: string[]
    mentionIds?: string[]
  }
}

/**
 * 列出用户Linear工作区中的文档
 */
type ListDocumentsSpec = {
  tool: 'list_documents'
  args: {
    query?: string
    limit?: number
    before?: string
    after?: string
    orderBy?: 'createdAt' | 'updatedAt'
    projectId?: string
    initiativeId?: string
    creatorId?: string
    includeArchived?: boolean
  }
}

这是运行mcpx list vercel时Vercel的样子：

vercel - Vercel MCP（需要OAuth）

/**
 * 搜索Vercel文档。
 * 使用此工具回答有关Vercel平台、功能和最佳实践的问题。
 */
type SearchVercelDocumentationSpec = {
  tool: 'search_vercel_documentation'
  args: {
    topic: string
    tokens?: number
  }
}

/**
 * 将当前项目部署到Vercel
 */
type DeployToVercelSpec = {
  tool: 'deploy_to_vercel'
  args: Record<string, unknown>
}

Context7：获取文档（无需认证）

mcpx call 'context7.resolve-library-id({ libraryName: "react" })'
mcpx call 'context7.get-library-docs({ path: "/websites/react_dev", topic: "hooks" })'

Linear：搜索文档（需要LINEAR_API_KEY）

LINEAR_API_KEY=sk_linear_example mcpx call 'linear.search_documentation({ query: "automations" })'

Chrome DevTools：快照当前标签页

mcpx call 'chrome-devtools.take_snapshot()'
mcpx call 'linear.create_comment({ issueId: "LNR-123", body: "Hello world" })'

调用语法： 函数语法 server.tool({ args }) 或数据格式 { tool: "server.tool", args: {...} }。两者都会被解析（而不是作为JS执行）。支持JSON5/YAML/TOML。

有用的标志：

• --config <path> -- 自定义配置文件（覆盖默认的./mcp.json + ~/.mcpx/mcp.json合并）。
• --root <path> -- 标准I/O命令的工作目录。
• --log-level <debug|info|warn|error> -- 调整详细程度（尊重MCPX_LOG_LEVEL）。
• --oauth-timeout <ms> -- 缩短/延长OAuth浏览器等待时间；同MCPX_OAUTH_TIMEOUT_MS / MCPX_OAUTH_TIMEOUT。
• --tail-log -- 流式输出工具响应中引用的日志文件最后20行。
• --output <format> -- 控制输出格式：toon（默认，适合LLM），json，text，或raw。
• --http-url <https://…> / --stdio "command …" -- 描述一个临时MCP服务器（根据需要配对--env KEY=value，--cwd，--name，和--persist <config.json>）。
• OAuth保护的服务器会在首次使用时自动触发身份验证。

提示：您可以完全跳过动词——mcpx firecrawl会自动运行mcpx list firecrawl，带点的令牌如mcpx linear.list_issues会分派到调用命令（包括拼写纠正）。

超时默认为30秒；如果您预计启动较慢，可以通过MCPX_LIST_TIMEOUT或MCPX_CALL_TIMEOUT覆盖。OAuth浏览器握手有一个单独的60秒宽限期；如果您需要更快地退出CLI以诊断顽固的身份验证流程，可以通过--oauth-timeout <ms>（或导出MCPX_OAUTH_TIMEOUT_MS）传递。

尝试一个MCP而不编辑配置

# 直接指向HTTPS MCP服务器
mcpx list --http-url https://mcp.linear.app/mcp --name linear

# 通过Bun运行本地标准I/O MCP服务器
mcpx call --stdio "bun run ./local-server.ts" --name local-tools

• 添加--persist ~/.mcpx/mcp.json（或任何路径）以保存推断的定义供未来运行使用。
• 如果确实需要访问明文端点，请使用--allow-http。
• 更多细节参见docs/adhoc.md（环境变量覆盖、工作目录、OAuth）。

调用语法

两种格式，都会被解析（而不是作为JavaScript执行）：

函数语法（对代理自然）：

mcpx call 'linear.create_issue({ title: "Bug", priority: 2, labels: ["urgent"] })'

数据格式（显式，支持JSON5/YAML/TOML）：

mcpx call '{ tool: "linear.create_issue", args: { title: "Bug", priority: 2 } }'

特性：

• 自动纠错。 键入listIssue？MCPX会自动建议list_issues。
• 类型规格。 mcpx list <server>打印TypeScript规格——可以直接复制粘贴到调用中。

批量调用

从标准输入或文件执行多个MCP工具调用。非常适合LLM驱动的工作流、自动化脚本和数据迁移。

# 从文件
cat batch-calls.txt | mcpx call

# 从heredoc（函数语法）
mcpx call << 'EOF'
linear.list_issues({ limit: 5 })
github.search_repos({ query: "mcp" })
EOF

# 数据格式也适用
mcpx call << 'EOF'
[
  { tool: "linear.list_issues", args: { limit: 5 } },
  { tool: "github.search_repos", args: { query: "mcp" } }
]
EOF

输入格式 支持函数语法和结构化数据：

// 函数语法（每行一个，对代理自然）
linear.create_issue({ title: "Fix bug", priority: 2, labels: ["bug", "urgent"] })
github.search_repos({ query: "mcp" })

// 数据格式（显式结构）
[
  { tool: "linear.create_issue", args: { title: "Fix bug", priority: 2, labels: ["bug", "urgent"] } },
  { tool: "github.search_repos", args: { query: "mcp" } }
]

输出 是TOON格式（紧凑，适合LLM）：

[2]:
  - tool: linear.create_issue
    output:
      id: ISS-123
      title: Fix bug
  - tool: github.search_repos
    output:
      items[1]{name,stars}: repo1,42

使用--output json覆盖为标准JSON：

[
  { tool: 'linear.create_issue', output: { id: 'ISS-123', title: 'Fix bug' } },
  { tool: 'github.search_repos', output: { items: [...] } },
]

错误处理：如果有任何调用失败，错误将被捕获在输出中，退出码为1：

{
  tool: 'linear.bad_tool',
  output: "参数验证失败：\n- 字段'id'：必需（期望字符串，但得到undefined）",
}

用例：

• LLM工具调用：生成批量文件并管道到mcpx
• 自动化脚本：每日站会、状态报告
• 数据迁移：从一个系统导出，导入另一个系统

参见examples/README.md和examples/batch-calls.txt以获取完整示例。

需要运行时或自动化样本？前往docs/tool-calling.md和docs/cli-reference.md。随时调用mcpx list <server>以获取符合CLI函数调用语法的TypeScript风格签名、可选参数提示和示例调用。

配置参考

mcp.json（项目）和~/.mcpx/mcp.json（用户）共享Cursor/Claude模式：

{
	mcpServers: {
		context7: {
			description: 'Context7文档MCP',
			baseUrl: 'https://mcp.context7.com/mcp',
			headers: {
				Authorization: '$env:CONTEXT7_API_KEY',
			},
		},
		'chrome-devtools': {
			command: 'bunx',
			args: ['chrome-devtools-mcp@latest'],
		},
	},
}

MCPX为您处理以下内容：

• ${VAR}, ${VAR:-fallback}, 和 $env:VAR 在两个文件中的头和环境条目中的插值。./mcp.json中定义的条目覆盖来自~/.mcpx/mcp.json的重复项。
• 在~/.mcpx/<server>/下自动缓存OAuth令牌，除非您覆盖tokenCacheDir。
• 标准I/O命令继承定义它们的文件的目录（导入或本地配置）。
• 首次运行时填充~/.mcpx/mcp.json，通过迁移Cursor/Claude/Codex/Windsurf/VS Code配置；迁移助手期间仅读取遗留的imports数组。

当您同时处理多个配置文件时，向CLI/运行时调用提供configPath或rootDir。

快速调试挂起的服务器

使用tmux保持长时间运行的CLI会话可见，同时调查滞留的MCP传输：

tmux new-session -- bun run mcpx:list

让它在后台运行，然后检查面板（tmux capture-pane -pt <session>），跟踪标准I/O日志，或者在命令退出后关闭会话。当您需要详细的句柄诊断时，搭配MCPX_DEBUG_HANG=1使用。更多细节：docs/tmux.md和docs/hang-debug.md。

致谢

MCPX受到mcporter的启发，但重新构建，以Token效率和LLM工作流作为首要设计目标。

许可证

MIT —— 查看LICENSE。

进一步阅读：docs/tool-calling.md，docs/adhoc.md，docs/tmux.md。