Asana MCP Server

npx -y @jtalk22/asana-mcp --setup

为何开发此服务 · 安装 · 75 个工具 · 组合工具 · Slack + Asana · 如实说明限制 · API 参考

为何开发此服务

Asana 官方的 V2 MCP 服务是受支持的托管方案：采用 OAuth、按工作区限定访问权限、整合任务写入，并在受支持的客户端中提供交互式确认。其工具集会随时间变化，因此请参考 Asana 的当前工具参考，而不要依赖过时的对照表。

如果你需要透明的本地 stdio 进程和直接的 REST API 覆盖范围，请选择此服务：

你可以同时使用两者：官方服务用于托管 OAuth，此软件包用于本地优先的 REST 工作流，或满足你的运营模式所需的其他功能。要使用此软件包，请创建个人访问令牌，运行 --setup，并让进程保持在你的计算机上。它只会与 app.asana.com 通信。

Slack + Asana 连续性预览

此软件包仍是完整的 75 工具、MIT 许可的本地服务。下文中的任何内容都不是解锁缺失工具的功能。

同一维护者还在开发 Keep the Thread，这是一个托管连续性层，面向已经使用 Slack 和 Asana、但不想再用一个仪表板的独立运营者或二至五人的团队。它的首个跨工具约定提出了一个更具体的问题：

在选定的 Asana 项目中，哪项 Slack 承诺缺失、未完成或已过时？

flowchart LR
    Slack["1–5 selected Slack channels"] --> Report["continuity_asana_discrepancy_report"]
    Asana["1 selected Asana project\nincomplete tasks only"] --> Report
    Report --> Gaps["matched commitments · gaps · task drift · next reviews"]
    Gaps --> Receipt["source IDs preserved\nwrites_performed: 0"]

托管版 Asana 连接器代码已上线，并且为只读，但公开 OAuth 激活仍在分阶段开放。请查看代表性输入／输出约定、检查实时连接器状态，或申请有范围限制的部署评审。创建、更新、完成或删除 Asana 任务，不属于托管版差异报告的功能范围。

安装

1. 获取令牌 — app.asana.com/0/my-apps → Personal access tokens → Create。然后任选其一：

npx -y @jtalk22/asana-mcp --setup    # stores it in the macOS Keychain (or ~/.asana-mcp.json, mode 600)

或者自行导出 ASANA_PAT。

2. 将服务添加到 MCP 客户端：

{
  "mcpServers": {
    "asana": {
      "command": "npx",
      "args": ["-y", "@jtalk22/asana-mcp"]
    }
  }
}

Claude Code 单行命令：claude mcp add asana -- npx -y @jtalk22/asana-mcp

3. 验证：

npx -y @jtalk22/asana-mcp --doctor   # token → identity → workspace → tool surface, as JSON

如果令牌恰好能访问一个工作区，系统会自动检测。若令牌能访问多个工作区：设置 ASANA_WORKSPACE_GID（doctor 会列出可选项），或在每次调用时传入 workspace。

75 个工具：读取、操作、设计

• 26 个读取工具 — 任务、项目、分区、用户、团队、标签、动态、子任务、依赖关系、附件、状态、项目组合、类型预输入（名称→GID），以及跨看板重复项检测；它能识别出一个任务位于多个看板时并非重复项。
• 40 个写入工具 — 创建/更新/完成/分配、评论、关注者、标签、依赖关系、成员关系、移动分区、日期（正确处理 start_on）、自定义字段（日期会封装，multi_enum 使用数组）、富文本备注（已清理）、附件（上传上限为 100MB）、批量操作、项目状态、项目组合、带异步任务轮询的模板，以及用于处理自动化程序改写刚刚写入内容的看板的 asana_set_notes_safe。
• 6 个架构/设计工具 — 创建自定义字段、扩展下拉选项、将字段附加到项目、分区，重新排序：Agent 能够构建看板，而不只是填充看板。
• 3 个破坏性操作 — delete_task / delete_project / delete_section 必须带有 confirm: true 才会执行。
• 本地文件边界 — attach_file 需要 confirm: true，且只能读取当前目录或 ASANA_MCP_FILE_ROOTS 中的文件。
• 只读批处理 — batch_ops 会在架构层和运行时层拒绝所有非 GET 操作。

每个工具都声明了 MCP 注解 — readOnlyHint、destructiveHint、idempotentHint、openWorldHint 和标题。遵循这些注解的客户端（Claude Code 会遵循）会在计划模式下自动允许读取操作、安全地并行处理读取操作，并对三个破坏性操作进行限制。

通过 ASANA_MCP_TOOLS=read（30 个工具）、write 或逗号分隔列表精简公开的工具集 — 分诊 Agent 的上下文不需要包含删除工具。

完整输入和语义：docs/API.md。

组合工具：一次调用，得到一个答案

这五个工具可替代多达十次调用的往返流程，基于每天在真实看板上的使用经验构建：

• asana_morning_brief — 一次调用，按逾期、今天到期、即将到期和受依赖关系阻塞分类未完成任务。
• asana_user_queue — 获取某人的完整队列，可分页突破 API 的 100 条搜索结果上限，按到期日期分类，并统计每个项目中的任务数量。用于回答“X 手头有哪些事情？”的调用。
• asana_portfolio_rollup — 汇总项目组合或项目列表中各项目的健康状况（未完成 / 逾期 / 本周完成 + 状态）。include_archived: true 会包含隐藏在已归档看板上的未完成任务 — 默认列表都会跳过这些任务。
• asana_board_rollup — 按分区汇总单个看板，并按分区汇总任意数量的自定义字段（“交易金额”“索赔金额”）；按名称检查截止日期字段是否逾期 — 字段会从看板自身设置中实时解析，不使用任何硬编码值。
• asana_triage_inbox — 从分诊列表批量创建（API 不支持批量创建），支持逐项覆盖设置，并在失败后继续处理。

坦诚说明限制

• Asana 的搜索 API 最多返回 100 条结果，且不支持分页。基于它构建的工具会说明这一点（truncated: true），而不会假装后面的结果不存在；asana_user_queue 和列表工具会在 REST API 支持的情况下继续分页。
• /batch 端点会在上游静默丢弃 PUT 请求体和 GET 选项，因此此服务不会通过它路由写入操作。asana_batch_ops 仅用于带默认字段的 GET 请求，其说明也明确写出了这一点。
• 故事中的评论富文本（html_text）会被 Asana 转成转义后的纯文本——因此这里的评论特意采用纯文本，而不是静默地显示得很难看。
• 日期自定义字段返回的是完整 ISO 时间戳；比较逾期情况前，会先将日期规范化为 YYYY-MM-DD（我们曾遇到并修复过一个导致错误地显示全部正常的问题）。
• PAT 只能读取自己的「我的任务」（读取他人的任务会返回 403）——asana_user_queue 使用的是适用于任何人的受派人路由。

更多信息请参阅 docs/TROUBLESHOOTING.md。

安全

你的 PAT 拥有与你的 Asana 登录相同的访问权限。它从 ASANA_PAT、macOS 钥匙串（asana-mcp）或 ~/.asana-mcp.json（以 600 权限写入）读取——绝不会记录到日志中，也绝不会发送到 api.asana.com 主机以外的任何地方。没有遥测，也不会主动向外发送数据；请阅读 SECURITY.md。

开发

npm ci && npm test          # 16 unit tests, no token needed
npm run doctor              # live check against your workspace
npm run api-docs            # regenerate docs/API.md from lib/tools.js

欢迎提交 PR——请参阅 CONTRIBUTING.md。MIT。

同一作者的其他作品：@jtalk22/slack-mcp — 不用阅读消息也能跟进 Slack。