MCP Server for Asana

Asana 的 MCP 服务

此 Asana 模型上下文协议服务实现让你能够通过 MCP 客户端（例如 Anthropic 的 Claude 桌面应用程序等）与 Asana API 交互。

有关 MCP 的更多详情，请参阅：

• https://www.anthropic.com/news/model-context-protocol
• https://modelcontextprotocol.io/introduction
• https://github.com/modelcontextprotocol

环境变量

• ASANA_ACCESS_TOKEN：（必需）你的 Asana 访问令牌
• READ_ONLY_MODE：（可选）设为 'true' 以禁用所有写入操作。在此模式下：
  • 修改 Asana 数据（创建、更新、删除）的工具将被禁用
  • create-task 提示词将被禁用
  • 只能执行读取操作 这适用于测试，或你希望确保无法对 Asana 工作区进行任何更改时。

用法

在你选择的 AI 工具中（例如：Claude Desktop），询问有关 Asana 任务、项目、工作区和／或评论的问题。提及“asana”一词可以提高大模型选择正确工具的概率。

示例：

我们的 Sprint 30 项目中有多少个未完成的 Asana 任务？

另一个示例：

工具

1. asana_list_workspaces
   • 列出 Asana 中所有可用的工作区
   • 可选输入：
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
   • 返回：工作区列表
2. asana_search_projects
   • 使用名称模式匹配在 Asana 中搜索项目
   • 必需输入：
     • workspace (string)：要在其中搜索的工作区
     • name_pattern (string)：用于匹配项目名称的正则表达式模式
   • 可选输入：
     • archived (boolean)：仅返回已归档的项目（默认值：false）
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
   • 返回：匹配的项目列表
3. asana_search_tasks
   • 使用高级筛选选项搜索工作区中的任务
   • 必需输入：
     • workspace (string)：要在其中搜索的工作区
   • 可选输入：
     • text (string)：要在任务名称和描述中搜索的文本
     • resource_subtype (string)：按任务子类型筛选（例如 milestone）
     • completed (boolean)：筛选已完成的任务
     • is_subtask (boolean)：筛选子任务
     • has_attachment (boolean)：筛选带有附件的任务
     • is_blocked (boolean)：筛选存在未完成依赖项的任务
     • is_blocking (boolean)：筛选有依赖任务的未完成任务
     • assignee、projects、sections、tags、teams 以及许多其他高级筛选条件
     • sort_by (string)：按 due_date、created_at、completed_at、likes、modified_at 排序（默认值：modified_at）
     • sort_ascending (boolean)：按升序排序（默认值：false）
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
     • custom_fields (object)：包含自定义字段筛选条件的对象
   • 返回：匹配的任务列表
4. asana_get_task
   • 获取特定任务的详细信息
   • 必需输入：
     • task_id (string)：要获取的任务 ID
   • 可选输入：
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
   • 返回：任务详细信息
5. asana_create_task
   • 在项目中创建新任务
   • 必需输入：
     • project_id (string)：要在其中创建任务的项目
     • name (string)：任务名称
   • 可选输入：
     • notes (string)：任务描述
     • html_notes (string)：采用类似 HTML 格式的任务描述
     • due_on (string)：截止日期，格式为 YYYY-MM-DD
     • assignee (string)：受托人（可以是 'me' 或用户 ID）
     • followers (array of strings)：要添加为关注者的用户 ID 数组
     • parent (string)：要将此任务设为其子任务的父任务 ID
     • projects (array of strings)：要将此任务添加到的项目 ID 数组
     • resource_subtype (string)：任务类型（default_task 或 milestone）
     • custom_fields (object)：将自定义字段 GID 字符串映射到其值的对象
   • 返回：已创建的任务信息
6. asana_get_task_stories
   • 获取特定任务的评论和动态
   • 必需输入：
     • task_id (string)：要获取动态的任务 ID
   • 可选输入：
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
   • 返回：任务动态／评论列表
7. asana_update_task
   • 更新现有任务的详细信息
   • 必需输入：
     • task_id (string)：要更新的任务 ID
   • 可选输入：
     • name (string)：任务的新名称
     • notes (string)：任务的新描述
     • html_notes (string)：采用类似 HTML 格式的任务描述（支持部分 HTML 标签）
     • due_on (string)：新的截止日期，格式为 YYYY-MM-DD
     • assignee (string)：新的受托人（可以是 'me' 或用户 ID）
     • followers (array)：要添加为关注者的用户 ID 数组
     • parent (string)：要将此任务移动到其下的父任务 ID
     • completed (boolean)：将任务标记为已完成或未完成
     • resource_subtype (string)：任务类型（default_task 或 milestone）
     • custom_fields (object)：将自定义字段 GID 字符串映射到其值的对象
   • 返回：已更新的任务信息
8. asana_get_project
   • 获取特定项目的详细信息
   • 必需输入：
     • project_id (string)：要获取的项目 ID
   • 可选输入：
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
   • 返回：项目详细信息
9. asana_get_project_task_counts
   • 获取项目中的任务数量
   • 必需输入：
     • project_id (string)：要获取任务数量的项目 ID
   • 可选输入：
     • opt_fields (string)：要包含的可选字段的逗号分隔列表
   • 返回：任务数量信息
10. asana_get_project_sections
    • 获取项目中的版块
    • 必需输入：
      • project_id (string)：要获取版块的项目 ID
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：项目版块列表
11. asana_create_task_story
    • 在任务上创建评论或动态
    • 必需输入：
      • task_id (string)：要添加动态的任务 ID
      • text (string)：动态／评论的文本内容
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已创建的动态信息
12. asana_add_task_dependencies
    • 设置任务的依赖项
    • 必需输入：
      • task_id (string)：要为其添加依赖项的任务 ID
      • dependencies (array of strings)：此任务所依赖的任务 ID 数组
    • 返回：已更新的任务依赖项
13. asana_add_task_dependents
    • 设置任务的依赖任务（依赖此任务的任务）
    • 必需输入：
      • task_id (string)：要为其添加依赖任务的任务 ID
      • dependents (array of strings)：依赖此任务的任务 ID 数组
    • 返回：已更新的任务依赖任务
14. asana_create_subtask
    • 为现有任务创建新子任务
    • 必需输入：
      • parent_task_id (string)：要在其下创建子任务的父任务 ID
      • name (string)：子任务名称
    • 可选输入：
      • notes (string)：子任务描述
      • due_on (string)：截止日期，格式为 YYYY-MM-DD
      • assignee (string)：受托人（可以是 'me' 或用户 ID）
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已创建的子任务信息
15. asana_get_multiple_tasks_by_gid
    • 根据 GID 获取多个任务的详细信息（最多 25 个任务）
    • 必需输入：
      • task_ids (array of strings or comma-separated string)：要获取的任务 GID（最多 25 个）
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：任务详细信息列表
16. asana_get_project_status
    • 获取项目状态更新
    • 必需输入：
      • project_status_gid (string)：要获取的项目状态 GID
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：项目状态信息
17. asana_get_project_statuses
    • 获取项目的所有状态更新
    • 必需输入：
      • project_gid (string)：要获取状态的项目 GID
    • 可选输入：
      • limit (number)：每页结果数（1-100）
      • offset (string)：分页偏移令牌
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：项目状态更新列表
18. asana_create_project_status
    • 为项目创建新的状态更新
    • 必需输入：
      • project_gid (string)：要为其创建状态的项目 GID
      • text (string)：状态更新的文本内容
    • 可选输入：
      • color (string)：状态颜色（green、yellow、red）
      • title (string)：状态更新标题
      • html_text (string)：状态更新的 HTML 格式文本
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已创建的项目状态信息
19. asana_delete_project_status
    • 删除项目状态更新
    • 必需输入：
      • project_status_gid (string)：要删除的项目状态 GID
    • 返回：删除确认信息
20. asana_set_parent_for_task
    • 设置任务的父任务，并确定子任务在该父任务的其他子任务中的位置
    • 必需输入：
      • task_id (string)：要操作的任务 ID
      • data (object)：
        • parent (string)：任务的新父任务；若无父任务则为 null
    • 可选输入：
      • insert_after (string)：要将任务插入其后的父任务子任务；若要插入列表开头则为 null
      • insert_before (string)：要将任务插入其前的父任务子任务；若要插入列表末尾则为 null
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已更新的任务信息
21. asana_get_tag
    • 获取特定标签的详细信息
    • 必需输入：
      • tag_gid (string)：标签的全局唯一标识符
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：标签详细信息
22. asana_get_tags_for_task
    • 获取任务的标签
    • 必需输入：
      • task_gid (string)：要操作的任务
    • 可选输入：
      • limit (number)：每页结果数。每页要返回的对象数量。值必须介于 1 和 100 之间。
      • offset (string)：偏移令牌。API 返回的下一页偏移量。
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：与任务关联的标签列表
23. asana_get_tasks_for_tag
    • 获取特定标签对应的任务
    • 必需输入：
      • tag_gid (string)：要获取任务的标签 GID
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
      • opt_pretty (boolean)：以“美化”格式提供响应
      • limit (integer)：每页要返回的对象数量。值必须介于 1 和 100 之间。
      • offset (string)：API 返回的下一页偏移量。
    • 返回：指定标签对应的任务列表
24. asana_get_tags_for_workspace
    • 获取工作区中的标签
    • 必需输入：
      • workspace_gid (string)：工作区或组织的全局唯一标识符
    • 可选输入：
      • limit (integer)：每页结果数。每页要返回的对象数量。值必须介于 1 和 100 之间。
      • offset (string)：偏移令牌。API 返回的下一页偏移量。
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：工作区中的标签列表
25. asana_update_tag
    • 更新现有标签
    • 必需输入：
      • tag_gid (string)：标签的全局唯一标识符
    • 可选输入：
      • name (string)：标签名称
      • color (string)：标签颜色。可选值包括：dark-pink、dark-green、dark-blue、dark-red、dark-teal、dark-brown、dark-orange、dark-purple、dark-warm-gray、light-pink、light-green、light-blue、light-red、light-teal、light-brown、light-orange、light-purple、light-warm-gray
      • notes (string)：关于标签的备注
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已更新的标签信息
26. asana_delete_tag
    • 删除标签
    • 必需输入：
      • tag_gid (string)：标签的全局唯一标识符
    • 返回：删除确认信息
27. asana_create_tag_for_workspace
    • 在工作区中创建新标签
    • 必需输入：
      • workspace_gid (string)：工作区或组织的全局唯一标识符
      • name (string)：标签名称
    • 可选输入：
      • color (string)：标签颜色。可选值包括：dark-pink、dark-green、dark-blue、dark-red、dark-teal、dark-brown、dark-orange、dark-purple、dark-warm-gray、light-pink、light-green、light-blue、light-red、light-teal、light-brown、light-orange、light-purple、light-warm-gray
      • notes (string)：关于标签的备注
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已创建的标签信息
28. asana_add_tag_to_task
    • 为任务添加标签
    • 必需输入：
      • task_gid (string)：要添加标签的任务 GID
      • tag_gid (string)：要添加到任务的标签 GID
    • 返回：成功响应
29. asana_remove_tag_from_task
    • 从任务中移除标签
    • 必需输入：
      • task_gid (string)：要从中移除标签的任务 GID
      • tag_gid (string)：要从任务中移除的标签 GID
    • 返回：成功响应
30. asana_add_project_to_task
    • 将现有任务添加到项目
    • 必需输入：
      • task_id (string)：要添加到项目的任务 ID
      • project_id (string)：要将任务添加到的项目 ID
    • 可选输入：
      • section (string)：要在项目中将任务添加到的版块 ID
      • insert_after (string)：要将此任务插入其后的任务 ID。insert_before、insert_after 或 section 最多只能指定一个。
      • insert_before (string)：要将此任务插入其前的任务 ID。insert_before、insert_after 或 section 最多只能指定一个。
    • 返回：确认任务已添加到项目的成功消息
    • 备注：如果未提供位置参数，任务将被添加到项目末尾
31. asana_remove_project_from_task
    • 从项目中移除任务
    • 必需输入：
      • task_id (string)：要从项目中移除的任务 ID
      • project_id (string)：要从中移除任务的项目 ID
    • 返回：确认任务已从项目中移除的成功消息
    • 备注：任务仍会保留在系统中，但不再属于该项目
32. asana_delete_task
    • 永久删除任务
    • 必需输入：
      • task_id (string)：要删除的任务 ID
    • 返回：确认任务已删除的成功消息
    • 备注：此操作无法撤销。任务将被永久删除。
33. asana_create_project
    • 在工作区或团队中创建新项目
    • 必需输入：
      • workspace (string)：要在其中创建项目的工作区 GID
      • name (string)：项目名称
    • 可选输入：
      • team (string)：团队 GID（组织工作区必需）
      • notes (string)：项目描述或备注
      • color (string)：项目颜色（例如 dark-pink、dark-green、light-blue）
      • privacy_setting (string)：隐私设置（public_to_workspace、private_to_team、private）
      • default_view (string)：默认视图（list、board、calendar、timeline）
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已创建的项目对象
34. asana_update_project
    • 更新项目详细信息（名称、描述等）
    • 必需输入：
      • project_id (string)：要更新的项目 GID
    • 可选输入：
      • name (string)：项目的新名称
      • notes (string)：项目的新纯文本描述
      • html_notes (string)：新的 HTML 格式描述（必须是有效的 Asana XML）
      • color (string)：项目颜色（例如 dark-pink、dark-green、light-blue）
      • privacy_setting (string)：隐私设置（public_to_workspace、private_to_team、private）
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已更新的项目信息
35. asana_create_section
    • 在项目中创建新版块
    • 必需输入：
      • project_id (string)：要在其中创建版块的项目 GID
      • name (string)：新版块的名称
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已创建的版块信息
36. asana_update_section
    • 更新版块（重命名）
    • 必需输入：
      • section_id (string)：要更新的版块 GID
      • name (string)：版块的新名称
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
    • 返回：已更新的版块信息
37. asana_delete_section
    • 从项目中删除版块
    • 必需输入：
      • section_id (string)：要删除的版块 GID
    • 返回：删除确认信息
38. asana_add_task_to_section
    • 将任务移动到其所属项目中的某个版块
    • 必需输入：
      • section_id (string)：要将任务添加到的版块 GID
      • task_id (string)：要移动的任务 GID
    • 可选输入：
      • insert_before (string)：要将任务插入其前的任务 GID
      • insert_after (string)：要将任务插入其后的任务 GID
    • 返回：成功确认信息
39. asana_get_subtasks
    • 获取给定任务的所有子任务。返回每个子任务的简要信息。
    • 必需输入：
      • task_gid (string)：父任务的 GID
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表（例如 'name,completed,assignee,due_on'）
    • 返回：子任务对象数组
40. asana_get_tasks_for_project
    • 获取项目中的所有任务。需要列出特定项目中的任务时，请使用此工具代替 search_tasks。此工具可用于 Asana 免费套餐（而 search_tasks 需要高级套餐）。支持分页和可选字段选择。
    • 必需输入：
      • project_id (string)：要获取任务的项目 GID
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
      • limit (number)：每页结果数（1-100）
      • offset (string)：上一响应中的分页偏移令牌
    • 返回：任务对象数组
41. asana_get_my_tasks
    • 获取已认证用户在某个工作区的“我的任务”列表中的任务
    • 必需输入：
      • workspace (string)：要从中获取“我的任务”的工作区 GID
    • 可选输入：
      • opt_fields (string)：要包含的可选字段的逗号分隔列表
      • completed_since (string)：仅返回此时间之后完成的任务（ISO 8601）。使用 'now' 可仅返回未完成的任务。
    • 返回：用户“我的任务”列表中的任务

提示词

1. task-summary

   • 根据任务的备注、自定义字段和评论，获取任务摘要和状态更新
   • 必需输入：
     • task_id (string)：要获取摘要的任务 ID
   • 返回：包含生成任务摘要说明的详细提示词

2. task-completeness

   • 分析任务描述是否包含完成任务所需的所有信息
   • 必需输入：
     • task_id (string)：要分析的任务 ID 或 URL
   • 返回：包含分析任务完整性说明的详细提示词

3. create-task

   • 根据指定详情创建新任务
   • 必需输入：
     • project_name (string)：要在其中创建任务的 Asana 项目名称
     • title (string)：任务标题
   • 可选输入：
     • notes (string)：任务备注或描述
     • due_date (string)：任务截止日期（YYYY-MM-DD 格式）
   • 返回：包含创建完整任务说明的详细提示词

资源

1. 工作区 - asana://workspace/{workspace_gid}

   • 将 Asana 工作区表示为资源
   • 每个工作区都作为单独的资源公开
   • URI 格式：asana://workspace/{workspace_gid}
   • 返回：包含工作区详情的 JSON 对象，包括：
     • name：工作区名称（string）
     • id：工作区全局 ID（string）
     • type：资源类型（string）
     • is_organization：工作区是否为组织（boolean）
     • email_domains：与工作区关联的电子邮件域名列表（string[]）
   • MIME 类型：application/json

2. 项目 - asana://project/{project_gid}

   • 用于按 GID 获取项目详情的模板资源
   • URI 格式：asana://project/{project_gid}
   • 返回：包含项目详情的 JSON 对象，包括：
     • name：项目名称（string）
     • id：项目全局 ID（string）
     • type：资源类型（string）
     • archived：项目是否已归档（boolean）
     • public：项目是否公开（boolean）
     • notes：项目描述/备注（string）
     • color：项目颜色（string）
     • default_view：默认视图类型（string）
     • due_date、due_on、start_on：项目信息日期（string）
     • workspace：包含工作区信息的对象
     • team：包含团队信息的对象
     • sections：项目中的分区对象数组
     • custom_fields：项目的自定义字段定义数组
   • MIME 类型：application/json

设置

1. 创建 Asana 账户：

   • 访问 Asana。
   • 点击“注册”。

2. 获取 Asana 访问令牌：

   • 你可以在 Asana 开发者控制台中生成个人访问令牌。
     • https://app.asana.com/0/my-apps
   • 详细信息请见此处：https://developers.asana.com/docs/personal-access-token

3. 安装选项：

   对于 Claude Desktop：

   将以下内容添加到你的 claude_desktop_config.json：

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

   对于 Claude Code：

   使用以下命令安装并配置 MCP 服务：

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

   将 <TOKEN> 替换为你的 Asana 访问令牌。

   对于 Codex CLI：

   将以下内容添加到你的 ~/.codex/config.toml：

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

   将 <TOKEN> 替换为你的 Asana 访问令牌。

如果你想安装 Beta 版本（尚未发布），可以使用：

• @roychri/mcp-server-asana@beta

你可以通过以下任一方式查找当前的 Beta 版本（如有）：

1. https://www.npmjs.com/package/@roychri/mcp-server-asana?activeTab=versions
2. npm dist-tag ls @roychri/mcp-server-asana

故障排除

如果遇到权限错误：

1. 确保你的 Asana 套餐允许 API 访问
2. 确认访问令牌和配置已在 claude_desktop_config.json 中正确设置。

贡献

克隆此仓库并开始动手开发。

使用 MCP Inspector 在本地测试

如果你想测试所做的更改，可以像这样使用 MCP Inspector：

npm run inspector

这会将客户端暴露在端口 5173，并将服务端暴露在端口 3000。

如果这些端口已被其他程序占用，可以使用：

CLIENT_PORT=5009 SERVER_PORT=3009 npm run inspector

许可证

此 MCP 服务采用 MIT 许可证。也就是说，你可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详情请参阅项目仓库中的 LICENSE 文件。