composio-mcp

Composio — CLI（主要方式）+ MCP（备用方式）

通过 Composio 将 AI Agent 连接到 1000 多款外部应用。此技能涵盖两种执行方式和完整的工具集。

路径	传输方式	身份验证	适用场景
A. CLI（主要方式）	PATH 中的 composio 二进制文件	ak_* 项目 API 密钥	无头服务器、脚本，以及任何可访问 shell 的 Agent。成功执行 composio login 后即可使用。
B. MCP（备用方式）	HTTP https://connect.composio.dev/mcp	x-consumer-api-key 中的 ck_* 消费者密钥	偏好工具调用而非 shell 的原生 MCP Agent。需要从控制面板获取消费者密钥。

两种方式使用相同的 Composio 后端，并提供相同的工具包。在无头环境中，CLI 是最省事的选择，因为它自带身份验证方式（composio login）。

决策流程

Need to use Composio?
├─ Agent has shell access? → Use CLI (Path A) → composio search/execute/link/run/proxy
└─ Agent is MCP-native only? → Use MCP (Path B) → mcp__composio__* tool calls

CLI 备用模式： 当 MCP 服务宕机或未配置时，CLI 可以执行 MCP 所能执行的所有操作——composio execute 可替代 MCP 工具调用，composio search 可替代 MCP 搜索，composio link 可替代 MCP 身份验证流程。

适用场景

• devin mcp list / claude mcp list 显示 composio 无法列出工具（身份验证错误）。

• 用户说“配置 Composio”“Composio MCP 无法工作”或“composio 身份验证失败”。

• composio execute <slug> 调用报告某个工具包尚未连接 → 运行 composio link <toolkit>。

• 需要找到合适的工具 slug → composio search "<task>"。

• 需要获取 MCP 备用方式所需的消费者密钥（ck_*）。

• 用户用英语请求或提及此技能（例如，“use /composio-mcp”、“run composio-mcp”）。

• 用户用葡萄牙语请求或提及此技能（例如：“use /composio-mcp”、“execute composio-mcp”）。

不适用场景

• 用户只想要通用的 composio-cli 速查表（slug、execute、search、link）——这属于上游的 composio-cli 技能。此技能侧重于设置、身份验证和 MCP 接线。
• 用户正在构建 Composio SDK 项目（TypeScript/Python）→ 直接使用 Composio 的 SDK 文档。

安全准则

• 安装前固定版本：始终为 composio-core 和 @composio/cli 安装明确指定的版本；不要在未指定版本的情况下运行裸命令 npm install -g。
• 运行 composio setup --yes 前先确认：在用户主机上自动安装 CLI 前，先询问用户；优先先执行 --dry-run。
• 执行前先检查：运行任何会修改数据或发送消息的工具前，使用 composio execute <slug> --get-schema 和 --dry-run。
• 保护密钥：绝不要记录、提交或回显 ak_* 或 ck_* 密钥。请使用环境变量或 Agent 的密钥存储。
• 工具 slug 仅从 composio search 或官方清单获取：不要编造 slug，也不要未经验证就信任用户提供的 slug。

---

路径 A — CLI（主要方式）

A.1 安装

安装前固定软件包版本。将 <VERSION> 替换为 npm view @composio/cli version 查询到的最新稳定版本，或项目要求的版本。

# Option 1: npm (recommended) — pinned versions
npm install -g composio-core@<VERSION> @composio/cli@<VERSION>

# Option 2: let Composio auto-install for your agent host
# Ask the user before auto-installing; prefer --dry-run first if available.
composio setup --target auto --yes --dry-run || composio setup --target auto --yes

验证：

composio --version
composio whoami    # should print JSON with email + org

A.2 对 CLI 进行身份验证

CLI 使用以 ak_* 开头的项目 API 密钥。有两种登录方式：

# Interactive (opens browser, polls for completion)
composio login

# Headless / CI: pass the key directly
composio login --user-api-key ak_your_key_here --yes

# No-browser flow: prints a URL + session key, you complete in any browser
composio login --no-browser --no-wait
# then later:
composio login --key <session-key>

密钥会存储在 ~/.composio/user_data.json 中，并作为 COMPOSIO_API_KEY 导出到 shell 配置文件中。验证：

composio whoami
# {"account_type":"human","email":"...","current_org_name":"..."}

如果 whoami 失败，请重新运行 composio login。

A.3 使用 CLI

CLI 分为两层：用于日常操作的核心命令和用于高级项目工作流的**composio dev**。

核心命令

命令	用途	示例
composio search	语义工具发现	composio search "send an email"
composio execute	运行工具	composio execute GMAIL_SEND_EMAIL -d '{...}'
composio link	连接应用账号	composio link github
composio listen	订阅触发事件	composio listen --toolkit github --trigger GITHUB_COMMIT_EVENT
composio run	使用辅助函数运行内联 TS/JS	composio run 'await execute("...")'
composio proxy	原始 API 访问	composio proxy https://api.github.com/user --toolkit github
composio login	进行身份验证	composio login --user-api-key ak_...
composio whoami	检查身份验证状态	composio whoami
composio setup	安装插件	composio setup --target auto
composio orgs	管理组织	composio orgs list
composio config	CLI 配置	composio config

默认工作流（execute → search → link）

1. 已知 slug 时，始终先运行 composio execute <slug>。
2. 并行调用 → 使用 composio execute -p/--parallel，并重复提供 <slug> -d <json> 参数组。
3. 工具包尚未连接？ → 运行 composio link <toolkit>，然后重试。
4. 参数不明确？ → 先运行 composio execute <slug> --get-schema 或 --dry-run，再进行猜测。
5. 不知道 slug？ → 运行 composio search "<task>"（将相关查询批量合并到一次调用中）。

# Known slug — just execute
composio execute GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'

# Unknown slug — search first
composio search "create a github issue"
composio search "send an email" --toolkits gmail

# Inspect before executing
composio execute GITHUB_CREATE_ISSUE --get-schema
composio execute GITHUB_CREATE_ISSUE --dry-run -d '{ owner: "acme", repo: "app", title: "Bug" }'

# Pass data from file or stdin
composio execute GITHUB_CREATE_ISSUE -d @issue.json
cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -

# Upload a local file
composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \
  --file ./image.png \
  -d '{ channels: "C123" }'

# Parallel independent calls
composio execute --parallel \
  GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi" }' \
  GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'

# Skip connection check (when you know the account is linked)
composio execute GITHUB_CREATE_ISSUE --skip-connection-check -d '{...}'

关键标志：

标志	用途
--get-schema	检查必需参数，但不执行
--dry-run	预览请求结构，但不执行操作
--file <path>	将本地文件传入仅包含一个可上传文件输入项的工具
--account <alias>	同一工具包存在多个已连接账号时，选择一个账号
--parallel / -p	在同一次调用中执行多个互不依赖的工具调用
--skip-connection-check	跳过已连接账号检查
--skip-tool-params-check	跳过基于缓存架构的输入验证
--skip-checks	跳过上述两项检查

composio run — 无需 SDK 的脚本执行

composio run 会执行内联 ESM JavaScript/TypeScript 代码片段，并预先注入经过身份验证的 execute()、search()、proxy() 以及实验性的 experimental_subAgent() 辅助函数。无需配置 SDK。

composio run '
  const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");
  console.log(me.data.login);
'

composio run '
  const [emails, issues] = await Promise.all([
    execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
    execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),
  ]);
  const brief = await experimental_subAgent(`Summarize:\n${emails.prompt()}\n${issues.prompt()}`);
  console.log(brief);
'

使用 zod 输出结构化数据：

composio run --logs-off '
  const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 5 });
  const brief = await experimental_subAgent(
    `Summarize these emails and count them.\n\n${emails.prompt()}`,
    { schema: z.object({ summary: z.string(), count: z.number() }) }
  );
  console.log(brief.structuredOutput);
'

注入的辅助函数： execute()、search()、proxy()、experimental_subAgent()、result.prompt()、z（zod）。

composio listen — 订阅触发事件

composio listen --toolkit github --trigger GITHUB_COMMIT_EVENT

订阅工具包的触发事件，并将其流式传输到 stdout。适用于响应式工作流和自动化。

composio dev — 高级工作流

开发者范围内的管理：脚手架、Playground 执行、日志、已连接账号、触发器和项目。

composio dev init                          # scaffold a project
composio dev toolkits list                 # browse all toolkits
composio dev toolkits info github          # inspect a toolkit
composio dev auth-configs list             # auth configs
composio dev connected-accounts list       # connected accounts
composio dev triggers list                 # trigger types
composio dev playground-execute            # playground execution
composio dev logs tools                    # browse tool logs

composio generate — 类型存根

composio generate --toolkits github gmail --output-dir ./src/types

完整命令列表请参阅 references/cli-reference.md。

---

路径 B — MCP 备用方案

B.1 获取消费者密钥（ck_*）

MCP 端点 https://connect.composio.dev/mcp 不接受 ak_* 项目 API 密钥。它需要以 ck_* 为前缀的消费者密钥，这是一种独立凭证。

ck_* 与 ak_* 的区别 — 消费者密钥（ck_*）用于验证连接到 Connect 端点的 MCP 客户端。项目 API 密钥（ak_*）用于验证后端 API 调用（backend.composio.dev/api/v3/...）和 CLI。两者相互独立，不能互相替代。

获取消费者密钥的方法：

1. 打开控制台：https://dashboard.composio.dev/
2. 前往 For You → Connect Settings → Sessions & API Key
3. 复制消费者密钥（以 ck_ 开头）
4. （可选）点击 Regenerate 轮换密钥 — 这会立即使所有 MCP 客户端使用的旧密钥失效。

B.2 配置 MCP 服务

MCP 服务是位于 https://connect.composio.dev/mcp 的可流式传输 HTTP 服务。它需要 x-consumer-api-key 标头。

通用配置（适用于任何 stdio/http MCP 客户端）

{
  "mcpServers": {
    "composio": {
      "type": "http",
      "url": "https://connect.composio.dev/mcp",
      "headers": {
        "x-consumer-api-key": "ck_your_consumer_key_here"
      }
    }
  }
}

使用环境变量替换（推荐 — 避免提交密钥）

{
  "mcpServers": {
    "composio": {
      "type": "http",
      "url": "https://connect.composio.dev/mcp",
      "headers": {
        "x-consumer-api-key": "${COMPOSIO_CONSUMER_KEY}"
      }
    }
  }
}

然后在 shell 配置文件（~/.bashrc / ~/.zshrc）中导出：

export COMPOSIO_CONSUMER_KEY="ck_your_consumer_key_here"

各平台配置 — 关键注意事项

每个 MCP 客户端平台都有自己的配置格式。字段名称不正确会导致服务被静默忽略（没有错误提示，只是没有工具）。完整对照表请参阅 references/platform-quirks.md。

平台	配置文件	根键	URL 字段	注意事项
Claude Code	~/.claude.json	mcpServers	url	type: "http"
Claude Desktop	claude_desktop_config.json	mcpServers	url	—
Cursor	~/.cursor/mcp.json	mcpServers	url	—
Devin CLI	~/.config/devin/mcp_config.json	mcpServers	url	devin mcp add CLI
Devin Desktop	~/.devin/mcp_config.json	mcpServers	serverUrl	不是 url！
OpenCode	~/.config/opencode/opencode.json	mcp	url	type: "remote"，使用 environment 而不是 env
Antigravity IDE/CLI	~/.gemini/config/mcp_config.json	mcpServers	serverUrl	不是 url！卸载时清除缓存
OpenClaw	OpenClaw 配置	mcp.servers	url	transport: "streamable-http"，openclaw mcp add CLI

最常见的 3 个静默失败陷阱：

1. Devin Desktop / Antigravity 使用 serverUrl（而不是 url）——使用 url 会导致配置被静默忽略。
2. OpenCode 使用 mcp（而不是 mcpServers）、environment（而不是 env），并且 command 是单个数组。
3. OpenCode 的环境变量替换使用 {env:VAR}，而不是 ${VAR}。

各平台对应的准确 JSON 配置块请参阅 references/mcp-config.md。

自动配置辅助工具

运行随附的辅助工具，检测所有已安装的平台，并为每个平台应用正确格式（处理 serverUrl 与 url、mcp 与 mcpServers、environment 与 env 的区别，以及 OpenClaw CLI）：

bash skills/composio-mcp/scripts/setup_composio_mcp.sh
# or with the key inline:
COMPOSIO_CONSUMER_KEY=ck_xxx bash skills/composio-mcp/scripts/setup_composio_mcp.sh
# dry-run (show what would change):
COMPOSIO_CONSUMER_KEY=ck_xxx bash skills/composio-mcp/scripts/setup_composio_mcp.sh --dry-run
# target one platform:
bash skills/composio-mcp/scripts/setup_composio_mcp.sh --platform cursor
# remove:
bash skills/composio-mcp/scripts/setup_composio_mcp.sh --remove

B.3 验证 MCP 服务

完成配置后，重启 Agent 并检查：

# From the agent (Claude Code / Devin):
#   mcp_list_tools for composio should return tools

# From the shell, test the endpoint directly:
curl -sS -X POST "https://connect.composio.dev/mcp" \
  -H "Content-Type: application/json" \
  -H "x-consumer-api-key: $COMPOSIO_CONSUMER_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# Expect: a JSON-RPC InitializeResult (not an "Authorization required" error)

如果看到 {"error":"Authorization required"}，则表示缺少、错误或已撤销使用者密钥。请重新检查控制面板，必要时轮换密钥。

B.4 MCP 工具接口

MCP 端点会公开与 CLI 相同的工具包。mcp_list_tools 成功后，工具会显示为 mcp__composio__<SLUG>（例如 mcp__composio__GMAIL_SEND_EMAIL）。底层 slug 与 CLI 完全相同——composio search 和 composio execute 使用相同的名称。

B.5 可选：在 MCP 服务上强制要求 API 密钥（组织级）

组织可以要求每个 MCP 请求除了使用者密钥外，还必须携带有效的项目 API 密钥（ak_*）：

curl -X PATCH "https://backend.composio.dev/api/v3/org/project/config" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -d '{"require_mcp_api_key": true}'

启用后，MCP 请求必须同时包含 x-consumer-api-key（ck_）和 x-api-key（ak_）。默认情况下，此功能处于禁用状态。

---

身份验证参考

凭据	前缀	存储位置	身份验证对象
项目 API 密钥	ak_*	~/.composio/user_data.json、$COMPOSIO_API_KEY	CLI 命令、backend.composio.dev API
使用者密钥	ck_*	仅在控制面板中；需粘贴到 MCP 配置中	MCP Connect 端点（connect.composio.dev/mcp）
已连接账号（每个工具包）	—	通过 composio link <toolkit> 使用浏览器 OAuth	单个应用的访问权限（Gmail、GitHub、Slack…）
AuthKit JWT	—	OAuth 流程	备用 MCP bearer 身份验证（少见；用于基于 OAuth 的部署）

身份验证流程图

┌─────────────────────────────────────────────────────────────┐
│  CLI path (ak_*)                                            │
│  composio login ──► ~/.composio/user_data.json              │
│  composio whoami ──► verify                                 │
│  composio link <toolkit> ──► browser OAuth per app          │
│  composio execute <slug> ──► uses ak_* + connected account  │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│  MCP path (ck_*)                                            │
│  dashboard → Connect Settings → copy ck_*                   │
│  patch mcp config: headers.x-consumer-api-key = ck_*        │
│  restart agent → mcp_list_tools(composio) → tools            │
│  (optional) require_mcp_api_key=true → also send x-api-key  │
└─────────────────────────────────────────────────────────────┘

---

工具发现与咨询

如何找到合适的工具

1. 语义搜索 — composio search "<describe the task>" 使用语义搜索，检索所有工具包。这是主要的发现机制。
2. 按工具包筛选 — 知道应用时，可使用 --toolkits <slug> 筛选。
3. 检查架构 — composio execute <slug> --get-schema 会在执行前显示必需的输入。
4. 试运行 — composio execute <slug> --dry-run -d '{...}' 可在不产生副作用的情况下验证。

工具清单

当前目录包含 30 个工具包／约 3,300 个工具／约 170 个触发器。完整的工具包分类和常见工具模式请参阅 references/tools-inventory.md。

工具包	Slug	工具	触发器
Gmail	gmail	61	2
GitHub	github	871	46
Slack	slack	158	9
Google Calendar	googlecalendar	45	7
Notion	notion	53	8
Jira	jira	97	17
HubSpot	hubspot	244	2
…	…	…	…

标签

工具带有标签，可供筛选。常见标签：

标签	含义
important	核心／高价值工具
destructiveHint	不可逆或会销毁数据
idempotentHint	可安全重试
createHint	创建资源
updateHint	修改资源
deleteHint	删除资源
readOnlyHint	无副作用
openWorldHint	结果取决于外部状态
batch	批量操作

---

将 CLI 用作 MCP 的备用方案

当 MCP 端点无法访问或尚未配置时，CLI 可以执行 MCP 能执行的所有操作：

MCP 操作	CLI 对应命令
mcp__composio__GMAIL_SEND_EMAIL	composio execute GMAIL_SEND_EMAIL -d '{...}'
工具发现	composio search "<task>"
账号关联	composio link <toolkit>
触发器订阅	composio listen --toolkit <toolkit> --trigger <slug>
原始 API 调用	composio proxy <url> --toolkit <toolkit>
多步工作流	composio run '<code>'

CLI 方式在无头服务器上更可靠，因为它会在本地处理身份验证（~/.composio/user_data.json 中的 ak_* 密钥），且不依赖 MCP 端点或使用者密钥。

---

故障排除

症状	原因	解决方法
composio whoami 失败／返回空内容	尚未登录	执行 composio login（或使用 --user-api-key ak_...）
composio execute 提示 "toolkit not connected"	尚未关联应用账号	执行 composio link <toolkit>，然后重试
MCP Failed to list tools for composio	缺少或错误的 x-consumer-api-key 标头	从控制台获取 ck_*，修改配置（B.2），然后重启 Agent
MCP Authorization required: Bearer token rejected	在需要 ck_* 的地方发送了 ak_*	使用使用者密钥（ck_*），而非项目 API 密钥
MCP Authorization required: No Authorization header	完全没有标头	在 MCP 配置中添加 x-consumer-api-key 标头
composio login 在无头服务器上卡住	浏览器流程需要显示器	使用 --no-browser --no-wait，然后使用 --key <session> 或 --user-api-key ak_...
工具显示正常，但执行时返回 401	已启用 require_mcp_api_key，但缺少 x-api-key	除 x-consumer-api-key 外，再添加 x-api-key: ak_* 标头
composio search 没有返回结果	缓存过期或未设置组织	执行 rm -rf ~/.composio/toolkits.json，然后重试

---

参考资料

• references/cli-reference.md — 完整的 composio CLI 命令参考（核心命令 + dev + generate + setup）。
• references/tools-inventory.md — 实时工具包清单（30 个工具包中约有 3300 个工具）和常见工具模式。
• references/mcp-config.md — 各平台完整的 JSON 配置块（Claude Code/Desktop、Cursor、Devin CLI/Desktop、OpenCode、Antigravity IDE/CLI、OpenClaw）。
• references/platform-quirks.md — 跨平台 MCP 配置差异矩阵（serverUrl 与 url、mcp 与 mcpServers、environment 与 env、env 替换语法、OpenClaw CDP 端口）。
• references/troubleshooting.md — 扩展故障排除指南（CLI 缓存、待处理登录、组织选择器、composio dev 项目）。
• scripts/setup_composio_mcp.sh — 检测所有已安装的平台，并使用正确格式为每个平台打补丁（处理 serverUrl/url、mcp/mcpServers、environment/env、OpenClaw CLI）。
• scripts/verify_composio.sh — 运行 whoami + curl 初始化探测，并列出几个工具，以确认端到端流程正常。
• Composio Connect 文档
• 消费者密钥与项目密钥的使用边界
• Devin CLI MCP 配置
• Antigravity MCP 文档
• OpenCode MCP 服务
• OpenClaw MCP 工具
• Cursor MCP 文档
• 上游 composio-cli 技能，提供完整的命令速查表。