Asana MCP Server

什么是 Asana MCP Server？

Asana MCP Server（@roychri/mcp-server-asana）是一个社区开发的 asana mcp server，让 Claude Desktop、Claude Code、Codex 等 AI 助手通过 Asana API 读取和管理 Asana 中的任务、项目、分区、标签和评论。

它通过 npx 在本地以 stdio 方式运行，使用 Asana 个人访问令牌进行认证。该项目由独立开发者以 MIT 许可证维护，并非 Asana 官方出品。Asana 另外提供官方远程 MCP 服务器 https://mcp.asana.com/v2/mcp，详见下文的对比部分。

如何使用 Asana MCP Server？

你需要准备 Node.js（用于运行 npx）、一个 Asana 账号，以及一个 Asana 个人访问令牌。令牌可以在 Asana 开发者控制台 app.asana.com/0/my-apps 中生成，具体步骤见 Asana 的个人访问令牌指南。

服务器读取两个环境变量：

• ASANA_ACCESS_TOKEN（必填）：你的 Asana 访问令牌。
• READ_ONLY_MODE（可选）：设为 true 后，所有创建、更新或删除数据的工具以及 create-task 提示词都会被禁用。

配置完成后，直接向 AI 助手询问 Asana 任务、项目或评论即可。README 提示，在提问中带上“asana”一词，模型更容易选中正确的工具。

Claude Desktop

在 claude_desktop_config.json 中加入以下内容，然后重启 Claude Desktop：

{
  "mcpServers": {
    "asana": {
      "command": "npx",
      "args": ["-y", "@roychri/mcp-server-asana"],
      "env": {
        "ASANA_ACCESS_TOKEN": "your-asana-access-token"
      }
    }
  }
}

Claude Code

用一条命令注册服务器，把 <TOKEN> 替换为你的访问令牌：

claude mcp add asana -e ASANA_ACCESS_TOKEN=<TOKEN> -- npx -y @roychri/mcp-server-asana

Codex

在 ~/.codex/config.toml 中加入：

[mcp_servers.asana]
command = "npx"
args = [
  "-y", "@roychri/mcp-server-asana"
]
env = {ASANA_ACCESS_TOKEN= "<TOKEN>"}

Cursor 和 VS Code

README 没有提供 Cursor 或 VS Code 的专门步骤。任何能启动 stdio MCP 服务器的客户端，都可以使用同样的 npx -y @roychri/mcp-server-asana 命令，并在环境变量中设置 ASANA_ACCESS_TOKEN，配置结构与上面的 Claude Desktop JSON 相同。

如需试用尚未正式发布的改动，可以改为安装 @roychri/mcp-server-asana@beta。

Asana MCP Server 的主要功能

• 41 个工具，覆盖工作区、项目、任务、子任务、分区、标签、评论和项目状态更新
• 高级任务搜索，可按文本、负责人、完成状态、阻塞或被阻塞状态、附件、自定义字段筛选并排序
• 管理任务依赖关系和被依赖任务，并可调整子任务的父任务
• 只读模式会隐藏所有写入工具，适合测试或共享工作区
• 三个内置提示词：task-summary、task-completeness 和 create-task
• 提供工作区（asana://workspace/{workspace_gid}）和项目（asana://project/{project_gid}）MCP 资源
• 从 npm 本地运行，只需一个访问令牌，无需 OAuth 应用

Asana MCP Server 工具

• 工作区与搜索： asana_list_workspaces、asana_search_projects（按正则匹配项目名）和 asana_search_tasks 用于定位内容；asana_get_my_tasks 返回当前用户的 My Tasks 列表。
• 任务： asana_get_task、asana_create_task、asana_update_task 和 asana_delete_task 覆盖任务的完整生命周期；asana_get_multiple_tasks_by_gid 一次最多获取 25 个任务。
• 子任务与依赖： asana_create_subtask、asana_get_subtasks、asana_set_parent_for_task、asana_add_task_dependencies 和 asana_add_task_dependents。
• 项目与分区： asana_get_project、asana_create_project、asana_update_project、asana_get_project_task_counts 和 asana_get_tasks_for_project，以及 asana_create_section、asana_add_task_to_section 等分区工具。
• 评论与状态更新： 评论使用 asana_get_task_stories 和 asana_create_task_story，状态更新使用 asana_get_project_statuses 和 asana_create_project_status。
• 标签： 用于创建、更新、删除、列出和添加标签的工具，例如 asana_add_tag_to_task。

Asana MCP Server 的使用场景

• 冲刺汇报：“How many unfinished asana tasks do we have in our Sprint 30 project?”
• 任务录入：把会议纪要转成指定项目中带截止日期和负责人的任务。
• 状态总结：使用 task-summary 提示词，或者提问“总结一下 Asana 中 Website Redesign 项目最近的状态更新”。
• 规划整理：为任务添加依赖、把任务移入分区，或把任务挂到某个父任务下。
• 个人待办梳理：“列出我在这个工作区里未完成的 Asana 任务”，由 asana_get_my_tasks 提供支持。
• 安全探索：设置 READ_ONLY_MODE=true 运行，让智能体只回答问题而不修改任何数据。

Asana MCP Server 与替代方案对比

• Asana 官方 MCP 服务器：Asana 托管的远程服务器地址为 https://mcp.asana.com/v2/mcp，使用 Streamable HTTP 和 OAuth，并为 Claude、ChatGPT、Claude Code、Codex、Cursor 和 VS Code 提供了配置文档（Asana 文档）。它无需本地安装，但编码类客户端需要 OAuth 应用的 client ID 和 client secret。Asana 早期的 beta 端点 https://mcp.asana.com/sse 已被弃用，关停日期为 05/11/2026。如果你需要厂商支持和 OAuth，选择官方服务器；如果你更想要本地进程、个人访问令牌和只读开关，选择这个社区项目。
• 其他项目管理工具：如果团队在其他平台管理工作，可以看看 ClickUp MCP Server、Trello MCP Server 或 Linear MCP Server。

Asana MCP Server 常见问题排查

• 权限错误：README 建议确认你的 Asana 套餐允许 API 访问，并检查 claude_desktop_config.json 中的令牌是否设置正确。
• 免费套餐下搜索无结果或失败：asana_search_tasks 依赖 Asana 搜索，README 说明它需要付费（premium）套餐。请改用适用于免费套餐的 asana_get_tasks_for_project。
• 写入工具不见了：检查 READ_ONLY_MODE 是否被设为 true，该模式会移除创建、更新和删除工具。
• 模型没有调用 Asana：在提问中加上“asana”一词。
• 本地测试改动：在仓库克隆目录中运行 npm run inspector 打开 MCP Inspector（客户端端口 5173，服务器端口 3000；可通过 CLIENT_PORT 和 SERVER_PORT 修改）。