MCP 服务器

MCP Server for Asana

这个服务器实现允许 AI 助手与 Asana 的 API 交互，使用户能够通过自然语言请求来管理任务、项目、工作区和评论。

README

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

用法

在你选择的 AI 工具（例如：Claude 桌面）中，询问关于 Asana 任务、项目、工作区和/或评论的内容。提及“asana”一词将增加 LLM 选择正确工具的机会。

示例：

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

另一个例子：

Claude Desktop Example

使用自定义字段

当使用自定义字段更新或创建任务时，请使用以下格式：

asana_update_task({
  task_id: "TASK_ID",
  custom_fields: {
    "custom_field_gid": value  // 值格式取决于字段类型
  }
})

值格式因字段类型而异：

枚举字段：使用选项的 enum_option.gid（不是显示名称）
文本字段：使用字符串
数字字段：使用数字
日期字段：使用 YYYY-MM-DD 格式的字符串
多选枚举字段：使用枚举选项 GID 的数组

查找自定义字段 GID

要查找自定义字段及其枚举选项的 GID：

使用 asana_get_task，并将 opt_fields 参数设置为包含自定义字段：

asana_get_task({
  task_id: "TASK_ID",
  opt_fields: "custom_fields,custom_fields.enum_options"
})

在响应中，查找 custom_fields 数组。每个自定义字段将具有：
- gid：自定义字段的唯一标识符
- name：自定义字段的显示名称
- resource_subtype：自定义字段的类型（文本、数字、枚举等）
- 对于枚举字段，检查 enum_options 数组以查找每个选项的 GID

示例：更新枚举自定义字段

// 首先，获取带有自定义字段的任务
const taskDetails = asana_get_task({
  task_id: "1234567890",
  opt_fields: "custom_fields,custom_fields.enum_options"
});

// 查找自定义字段 GID 和枚举选项 GID
const priorityFieldGid = "11112222";  // 来自 taskDetails.custom_fields
const highPriorityOptionGid = "33334444";  // 来自优先级字段的 enum_options

// 使用自定义字段更新任务
asana_update_task({
  task_id: "1234567890",
  custom_fields: {
    [priorityFieldGid]: highPriorityOptionGid
  }
});

工具

asana_list_workspaces
- 列出 Asana 中所有可用的工作区
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：工作区列表
- 注意：如果设置了 DEFAULT_WORKSPACE_ID，则只会返回该工作区，而不会获取所有工作区
asana_search_projects
- 使用名称模式匹配在 Asana 中搜索项目
- 必需输入：
  - name_pattern (string): 用于匹配项目名称的正则表达式模式
- 可选输入：
  - workspace (string): 要搜索的工作区（如果设置了 DEFAULT_WORKSPACE_ID，则为可选）
  - team (string): 用于过滤项目的团队
  - archived (boolean): 仅返回已存档的项目（默认值：false）
  - limit (number): 每页结果数 (1-100)
  - offset (string): 分页偏移令牌
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：匹配的项目列表
- 注意：如果未设置 DEFAULT_WORKSPACE_ID，则必须指定工作区或团队
asana_search_tasks
- 使用高级过滤选项在工作区中搜索任务
- 必需输入：
  - workspace (string): 要搜索的工作区（如果设置了 DEFAULT_WORKSPACE_ID，则为可选）
- 可选输入：
  - text (string): 要在任务名称和描述中搜索的文本
  - resource_subtype (string): 按任务子类型过滤（例如，里程碑）
  - 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): 包含自定义字段过滤器的对象
- 返回：匹配的任务列表
asana_get_task
- 获取有关特定任务的详细信息
- 必需输入：
  - task_id (string): 要检索的任务 ID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：详细的任务信息
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 字符串映射到其值的对象
- 返回：已创建的任务信息
asana_get_task_stories
- 获取特定任务的评论和故事
- 必需输入：
  - task_id (string): 要获取故事的任务 ID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：任务故事/评论列表
asana_update_task
- 更新现有任务的详细信息
- 必需输入：
  - task_id (string): 要更新的任务 ID
- 可选输入：
  - name (string): 任务的新名称
  - notes (string): 任务的新描述
  - due_on (string): YYYY-MM-DD 格式的新截止日期
  - assignee (string): 新的受让人（可以是“me”或用户 ID）
  - completed (boolean): 将任务标记为已完成或未完成
  - resource_subtype (string): 任务的类型（default_task 或 milestone）
  - custom_fields (object): 将自定义字段 GID 字符串映射到其值的对象
- 返回：已更新的任务信息
asana_get_project
- 获取有关特定项目的详细信息
- 必需输入：
  - project_id (string): 要检索的项目 ID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：详细的项目信息
asana_get_project_task_counts
- 获取项目中任务的数量
- 必需输入：
  - project_id (string): 要获取任务计数的项目 ID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：任务计数信息
asana_get_project_sections
- 获取项目中的部分
- 必需输入：
  - project_id (string): 要获取部分的项目 ID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：项目部分列表
asana_create_task_story
- 在任务上创建评论或故事
- 必需输入：
  - task_id (string): 要将故事添加到的任务 ID
  - text (string): 故事/评论的文本内容
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：已创建的故事信息
asana_add_task_dependencies
- 设置任务的依赖关系
- 必需输入：
  - task_id (string): 要添加依赖关系的任务 ID
  - dependencies (array of strings): 此任务依赖的任务 ID 数组
- 返回：已更新的任务依赖关系
asana_add_task_dependents
- 设置任务的依赖项（依赖于此任务的任务）
- 必需输入：
  - task_id (string): 要添加依赖项的任务 ID
  - dependents (array of strings): 依赖于此任务的任务 ID 数组
- 返回：已更新的任务依赖项
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): 要包含的可选字段的逗号分隔列表
- 返回：已创建的子任务信息
asana_add_followers_to_task
- 将关注者添加到任务
- 必需输入：
  - task_id (string): 要添加关注者的任务 ID
  - followers (array of strings): 要添加到任务的关注者的用户 ID 数组
- 返回：已更新的任务信息
asana_get_multiple_tasks_by_gid
- 通过其 GID 获取有关多个任务的详细信息（最多 25 个任务）
- 必需输入：
  - task_ids (array of strings or comma-separated string): 要检索的任务 GID（最多 25 个）
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：详细的任务信息列表
asana_get_project_status
- 获取项目状态更新
- 必需输入：
  - project_status_gid (string): 要检索的项目状态 GID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：项目状态信息
asana_get_project_statuses
- 获取项目的所有状态更新
- 必需输入：
  - project_gid (string): 要获取状态的项目 GID
- 可选输入：
  - limit (number): 每页结果数 (1-100)
  - offset (string): 分页偏移令牌
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：项目状态更新列表
asana_create_project_status
- 为项目创建一个新的状态更新
- 必需输入：
  - project_gid (string): 要创建状态的项目 GID
  - text (string): 状态更新的文本内容
- 可选输入：
  - color (string): 状态的颜色（绿色、黄色、红色）
  - title (string): 状态更新的标题
  - html_text (string): 状态更新的 HTML 格式文本
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：已创建的项目状态信息
asana_delete_project_status
- 删除项目状态更新
- 必需输入：
  - project_status_gid (string): 要删除的项目状态 GID
- 返回：删除确认
asana_set_parent_for_task
- 设置任务的父任务，并将子任务放置在该父任务的其他子任务中
- 必需输入：
  - task_id (string): 要操作的任务 ID
  - parent (string): 任务的新父任务，如果没有父任务，则为 null
- 可选输入：
  - insert_after (string): 要将任务插入其后的父任务的子任务，如果要在列表的开头插入，则为 null
  - insert_before (string): 要将任务插入其前的父任务的子任务，如果要在列表的末尾插入，则为 null
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：已更新的任务信息
asana_get_tasks_for_tag
- 获取特定标签的任务
- 必需输入：
  - tag_gid (string): 要检索任务的标签 GID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
  - opt_pretty (boolean): 以“漂亮”格式提供响应
  - limit (integer): 每页返回的对象数。该值必须介于 1 和 100 之间。
  - offset (string): API 返回的下一页的偏移量。
- 返回：指定标签的任务列表
asana_get_tags_for_workspace
- 获取工作区中的标签
- 必需输入：
  - workspace_gid (string): 工作区或组织的全局唯一标识符（如果设置了 DEFAULT_WORKSPACE_ID，则为可选）
- 可选输入：
  - limit (integer): 每页结果数。每页返回的对象数。该值必须介于 1 和 100 之间。
  - offset (string): 偏移令牌。API 返回的下一页的偏移量。
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：工作区中的标签列表
asana_create_section_for_project
- 在项目中创建一个新部分
- 必需输入：
  - project_id (string): 要在其中创建部分的项目 ID
  - name (string): 要创建的部分的名称
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：已创建的部分信息
asana_add_task_to_section
- 将任务添加到项目中的特定部分
- 必需输入：
  - section_id (string): 要将任务添加到的部分 ID
  - task_id (string): 要添加到部分的任务 ID
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：操作结果
asana_create_project
- 在工作区中创建一个新项目
- 必需输入：
  - workspace_id (string): 要在其中创建项目的工作区 ID（如果设置了 DEFAULT_WORKSPACE_ID，则为可选）
  - name (string): 要创建的项目的名称
  - team_id (string): 组织工作区必需 - 要与项目共享的团队 GID
- 可选输入：
  - public (boolean): 项目是否对组织公开（默认值：false）
  - archived (boolean): 项目是否已存档（默认值：false）
  - color (string): 项目的颜色（浅绿色、浅橙色、浅蓝色等）
  - layout (string): 项目的布局（看板、列表、时间线或日历）
  - default_view (string): 项目的默认视图（列表、看板、日历、时间线或甘特图）
  - due_on (string): 此项目到期的日期（YYYY-MM-DD 格式）
  - start_on (string): 此项目的工作开始的日期（YYYY-MM-DD 格式）
  - notes (string): 与项目关联的自由格式文本信息
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：已创建的项目信息
asana_get_teams_for_user
- 获取用户有权访问的团队
- 必需输入：
  - user_gid (string): 要获取团队的用户 GID。使用“me”获取当前用户的团队。
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：用户有权访问的团队列表
asana_get_teams_for_workspace
- 获取工作区中的团队
- 必需输入：
  - workspace_gid (string): 要获取团队的工作区 GID（如果设置了 DEFAULT_WORKSPACE_ID，则为可选）
- 可选输入：
  - opt_fields (string): 要包含的可选字段的逗号分隔列表
- 返回：工作区中的团队列表
asana_list_workspace_users
- 获取工作区中的用户
- 必需输入：
  - workspace_id (string): 要获取用户的工作区 ID（如果设置了 DEFAULT_WORKSPACE_ID，则为可选）
- 可选输入：
  - limit (integer): 每页结果数 (1-100)
  - offset (string): 分页偏移令牌
  - opt_fields (string): 要包含的可选字段的逗号分隔列表（默认为“name,email”）
  - auto_paginate (boolean): 是否自动获取所有页面
  - max_pages (integer): auto_paginate 为 true 时要获取的最大页数
- 返回：工作区中的用户列表
asana_get_project_hierarchy
- 获取 Asana 项目的完整分层结构，包括部分、任务和子任务
- 必需输入：
  - project_id (string): 要获取层次结构的项目 ID
- 可选输入：
  - include_completed_tasks (boolean): 包括已完成的任务（默认值：false）
  - include_subtasks (boolean): 包括每个任务的子任务（默认值：true）
  - include_completed_subtasks (boolean): 包括已完成的子任务（默认值：遵循 include_completed_tasks）
  - max_subtask_depth (number): 要检索的子任务的最大深度（默认值：1）
  - opt_fields_tasks (string): 任务的可选字段
  - opt_fields_subtasks (string): 子任务的可选字段
  - opt_fields_sections (string): 部分的可选字段
  - opt_fields_project (string): 项目的可选字段
  - limit (number): 每页最大结果数 (1-100)
  - offset (string): 来自先前响应的分页令牌
  - auto_paginate (boolean): 是否自动获取所有页面
  - max_pages (number): auto_paginate 为 true 时要获取的最大页数
- 返回：具有统计信息的分层项目结构

提示词

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

资源

无

设置

创建一个 Asana 帐户：
- 访问 Asana。
- 点击“注册”。
检索 Asana 访问令牌：
- 你可以从 Asana 开发者控制台生成个人访问令牌。
  - https://app.asana.com/0/my-apps
- 更多详细信息请参见：https://developers.asana.com/docs/personal-access-token
可选：获取你的默认工作区 ID：
- 如果你主要在一个工作区中工作，则可以设置默认工作区 ID。
- 使用 Asana API 列出你的工作区，或者转到 Asana 中的工作区并从 URL 复制 ID。
- 设置默认工作区 ID 后，你无需为每个 API 调用指定工作区。
- 如果没有默认工作区，服务器将调用 asana_list_workspaces 以获取可用工作区的列表。

配置 Claude 桌面：将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "asana": {
      "command": "npx",
      "args": ["-y", "@cristip73/mcp-server-asana"],
      "env": {
        "ASANA_ACCESS_TOKEN": "your-asana-access-token",
        "DEFAULT_WORKSPACE_ID": "your-default-workspace-id"
      }
    }
  }
}

故障排除

如果遇到权限错误：

确保你拥有的 Asana 计划允许 API 访问
确认访问令牌和配置已在 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 文件。