asana-admin-mcp
asana-admin-mcp
MCP 服务器,用于整理 Asana 结构 — 项目组合、自定义字段/下拉列表、项目、分区 填补标准 Asana connector 无法完成的部分(那个连接器专注于 task/read)
⚠️ Dashboard 无法做到——这不是本 MCP 的限制
Asana 完全未开放用于 Dashboard / chart / widget / project view tab 的 public API (翻遍了官方 OpenAPI spec 中的全部 175 个 endpoint——没有一个)
唯一能自动化的方式是 project_duplicate——规格说明指出,在 duplicate project 时
Project Views(List / Board / Dashboard 标签页)总是会被一并复制,并且无法关闭
→ 在一个“原型项目”中配置好 Dashboard,然后每次需要新项目时就 duplicate
🟡 尚未验证: 规格说明写着“Project Views”会跟随,但没有明确说明 Dashboard 中配置的图表 是否也会跟随,还是只会得到空标签页——无法通过 API 检查(没有读取图表的 endpoint),必须亲眼查看 2026-08-17 的 smoke test 复制的是没有图表的项目,因此还不能回答这个问题
注意:Project Template 不会带上 Dashboard(这仍是 Asana 论坛中悬而未决的功能请求) 必须使用 duplicate,而不是 template
Related MCP server: asana-mcp
安装
1. 先获取 Asana token(每个人都必须有自己的)
按照 GET-TOKEN.md 操作 → 保存到 ~/.asana_token
printf '%s' 'วาง_token_ตรงนี้' > ~/.asana_token && chmod 600 ~/.asana_tokentoken 与个人权限绑定,严禁使用他人的——Asana 的日志中会显示 token 所有者的名字
2. 安装插件(推荐)
在 Claude Code 中输入两行:
/plugin marketplace add plakorp/asana-admin-mcp
/plugin install asana-admin@asana-admin-mcpClaude Code 会自动 clone repo 并运行 npm ci,然后注册 MCP——无需手动修改 ~/.claude.json
之后要更新就运行 /plugin update
本机需要 Node 20+(用 node -v 检查)
方法 2——手动安装(如果不想用插件)
克隆 repo 后双击 ติดตั้ง-asana-admin-mcp.command
脚本会请求 token,运行 npm install,然后写入 ~/.claude.json(每次都会备份)
不要同时使用这两种方法——否则会得到两个重名的
asana-adminMCP
Token 优先从环境变量 ASANA_TOKEN 读取,如果没有则回退到 ~/.asana_token
→ token 绝不会出现在 repo 中,也不需要放在 ~/.claude.json 里
工具(21)
每个 tool 都接收 gid 而不是名称——先用 asana_find 将名称转换成 gid
发现
工具 | 说明 |
| 自己 + 所有 workspace(从这里开始,因为几乎所有 create 操作都需要 |
| typeahead 按名称查找 gid — 项目 / 项目组合 / custom_field / 任务 / 团队 / 用户 / 标签 / 目标 |
| workspace 中的自定义字段或绑定到 project/portfolio 的字段——返回带 gid 的 |
项目组合
工具 | 说明 |
| 创建项目组合 |
| 重命名 / 更改颜色 / 设置公开 |
| 按实际显示顺序查看项目组合中的项目 |
| 将项目添加到项目组合 + 可指定位置( |
| 移除项目(必须传 |
自定义字段 / 下拉列表
工具 | 说明 |
| 创建字段 — |
| 重命名 / 修改描述 |
| 为下拉列表添加选项 + 可指定位置 |
| 重命名 / 更改颜色 / 设置 |
| 对下拉列表选项排序 |
| 将字段绑定到 project 或 portfolio( |
Asana 无法删除下拉列表选项——只能通过
enabled:false来停用;之前选中该选项的任务仍会保留原值
项目 / 分区
工具 | 说明 |
| 创建项目(在 organization 中需要 |
| 重命名 / 备注 / 颜色 / |
| 复制项目,会带上 Dashboard——这是 dashboard 问题的唯一解决办法(返回 job,异步执行) |
| 按顺序列出 section + gid |
| 添加 section + 可指定位置 |
| 重命名 section |
| 对 section 排序 |
有意不提供删除 project / portfolio / custom field 的工具——删除这些后无法恢复,请在网页端操作
颜色(适用于 portfolio / project / enum option)
none red orange yellow-orange yellow yellow-green green blue-green
aqua blue indigo purple magenta hot-pink pink cool-gray
测试
ASANA_TOKEN=$(cat ~/.asana_token) npm run smoke在 token 的第一个 workspace 中创建真实对象,名称以 ZZ-mcp-smoke-* 开头 → 检查所有 tool → 自行全部删除
如果不提供 token,则只会运行前半部分(server 启动 + 列出 tools)
运行说明
429 → 根据
Retry-After自动重试 3 次Asana 的错误会返回来自 API 的真实消息(指出缺少哪个字段 / 哪个 gid 错误),而不只是状态码
未传递的字段不会被修改——只传
name的portfolio_update不会清除颜色
Available Tools
23 toolsasana_findFind gid by nameA
Typeahead search that turns a name you can see in the Asana UI into the gid every other tool needs.
Inputs: type (required), query (required), workspace_gid (required), count.
asana_list_custom_fieldsList custom fieldsA
Custom fields in a workspace, or the ones attached to a project/portfolio. Returns enum_options with their gids — the input for every dropdown tool.
Inputs: project_gid, portfolio_gid, workspace_gid.
asana_whoamiWho am IA
The authenticated user and their workspaces. Call this first — almost every create call needs a workspace_gid.
Inputs: no named parameters.
custom_field_attachAttach custom field to project or portfolioB
Make an existing custom field available on a project or a portfolio.
Inputs: custom_field_gid (required), project_gid, insert_after, is_important, +2 more.
custom_field_createCreate custom fieldB
Create a workspace custom field. For a dropdown use type 'enum' (single-select) or 'multi_enum' (multi-select) and pass enum_options.
Inputs: name (required), type (required), workspace_gid (required), precision, +2 more.
custom_field_updateRename / update custom fieldA
Change a custom field's name or description. Enum values are edited with the enum_option_* tools.
Inputs: custom_field_gid (required), name, description.
enum_option_createCreate dropdown valueA
Add a value to an enum / multi_enum custom field. Appended at the end unless you give a position.
Inputs: name (required), custom_field_gid (required), color, insert_after, +1 more.
enum_option_reorderReorder dropdown valueA
Move an existing dropdown value to a new position within its custom field.
Inputs: enum_option_gid (required), custom_field_gid (required), after_enum_option, before_enum_option.
enum_option_updateRename / disable dropdown valueA
Rename, recolor, or disable a dropdown value. Asana has no delete — set enabled:false to retire a value; tasks already holding it keep it.
Inputs: enum_option_gid (required), name, color, enabled.
member_addAdd member to project or portfolioA
Give a person or team access to a project or portfolio. NOTE Asana's own limits: a project can only be admin / editor / commenter — there is no view-only level for projects, so 'commenter' is the least access possible. A portfolio can be admin / editor / viewer.
Inputs: member_gid (required), parent_gid (required), access_level (required).
member_listList members of a project or portfolioB
Who currently has access, and at what level.
Inputs: parent_gid (required).
portfolio_add_itemAdd project to portfolioA
Add a project (or sub-portfolio) to a portfolio, optionally at a chosen position. Adding an item that is already present moves it to that position.
Inputs: item_gid (required), portfolio_gid (required), insert_after, insert_before.
portfolio_createCreate portfolioC
Create a portfolio in a workspace.
Inputs: name (required), workspace_gid (required), color, public.
portfolio_list_itemsList portfolio itemsC
The projects/portfolios inside a portfolio, in their current display order.
Inputs: portfolio_gid (required).
portfolio_remove_itemRemove item from portfolioA
Remove a project from a portfolio. This also drops any portfolio-level custom field values set on that project.
Inputs: confirm (required), item_gid (required), portfolio_gid (required).
portfolio_updateRename / update portfolioA
Change a portfolio's name, color, or visibility. Only the fields you pass are touched.
Inputs: portfolio_gid (required), name, color, public.
project_createCreate projectB
Create a project in a workspace (team_gid is required in an organization).
Inputs: name (required), workspace_gid (required), color, notes, +3 more.
project_duplicateDuplicate projectA
Copy a project. Tasks, project views (List/Board/Dashboard tabs) and rules are always carried over — this is the only way to give a new project a preconfigured Dashboard, since Asana exposes no dashboard/chart API. Returns a job; duplication finishes asynchronously.
Inputs: name (required), project_gid (required), include, team_gid.
project_list_sectionsList project sectionsB
Sections of a project in display order — the gids needed by section_reorder.
Inputs: project_gid (required).
project_updateRename / update projectC
Change a project's name, notes, color, default view, or archived state.
Inputs: project_gid (required), name, color, notes, +3 more.
section_createCreate sectionB
Add a section to a project, optionally at a chosen position.
Inputs: name (required), project_gid (required), insert_after, insert_before.
section_reorderReorder sectionC
Move an existing section to a new position within its project.
Inputs: project_gid (required), section_gid (required), after_section, before_section.
section_updateRename sectionA
Rename an existing section.
Inputs: name (required), section_gid (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool targets a distinct resource and action: user info, members, projects, portfolios, custom fields, sections, and search. There is no overlap in purpose, and descriptions clearly differentiate them.
Most tools follow a consistent 'resource_verb' pattern (e.g., portfolio_create, custom_field_attach, section_reorder), but a few use a generic 'asana_' prefix (asana_whoami, asana_find) and 'project_list_sections' mixes resource prefixes, creating minor inconsistency.
With 23 tools, the server is slightly on the higher side but still well-scoped for Asana administration. Each tool serves a clear purpose, and the count is justified by the breadth of admin operations covered.
The tool set covers core admin operations like project/portfolio/folder/section CRUD, custom field management, and member access. However, it lacks delete operations for projects, portfolios, and members, and is missing a general listing tool for projects/portfolios, which are notable gaps for an admin surface.
Maintenance
Related MCP Connectors
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that uses AI to generate structured Asana project plans from diverse sources like text, PDFs, and meeting transcripts. It enables users to preview, generate, and directly sync detailed task lists, subtasks, and dependencies into Asana.1MIT
- AlicenseBqualityCmaintenanceMCP server for the Asana API that allows AI agents to read and optionally write to Asana tasks, comments, and custom fields, with tiered access controls and no delete tools.832 npmMIT
- AlicenseNot gradedqualityDmaintenanceHigh-performance MCP server that transforms how AI assistants interact with Asana, enabling complex task hierarchies and batch operations for efficient project management.6 npm3MIT
- AlicenseAqualityDmaintenanceA local MCP server for Asana that uses a personal access token to read and manage Asana projects, tasks, sections, and comments via the standard Asana REST API.8MIT