Claude Code 接入 Asana V2 MCP 服务器：OAuth 应用创建与 `claude mcp add` 连接配置实战

AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载本指南围绕本仓库 external_plugins/asana 插件中的 asana-setup.md 命令文档展开完整讲解如何在 Claude Code 中一次性配置 Asana V2 MCP 服务器连接从创建自己的 Asana OAuth 应用、注册本地回调地址到通过claude mcp add命令注册服务器再到浏览器授权、/mcp验证与实际调用。读完本文你将掌握 Asana V2 的 OAuth 认证机制、claude mcp add各关键参数的真实含义以及invalid_redirect_uri、invalid_client两类高频错误的排查方法。背景为什么 Asana V2 必须自带 OAuth 应用Asana 的 V2 MCP 服务器地址为https://mcp.asana.com/v2/mcp与 V1 最大的差异在于V2 不支持 Dynamic Client RegistrationDCR因此不存在零配置直连的方案每个用户都必须携带自己预先注册的client_id与client_secret才能完成 OAuth 授权流程。这一点在 external_plugins/asana/README.md 中有明确说明V1 beta 服务器https://mcp.asana.com/sse已被弃用将于2026 年 8 月 5 日周三正式关闭。迁移到 V2 的必经之路就是完成本文所述的一次性 OAuth 应用注册与连接配置。在 Claude Code 中最快的操作路径是直接运行/asana-setup斜杠命令让 Claude 按照 asana-setup.md 打印出完整步骤也可以完全手动完成下面的配置。理解命令文档本身frontmatter 与执行约束在深入配置步骤之前先理解asana-setup.md这个命令文件自身的结构这有助于你安全地使用它。命令文件的 frontmatter该文件开头包含标准的 YAML frontmatter--- description: Set up the Asana V2 MCP server connection (one-time OAuth app claude mcp add) argument-hint: [client_id] ---根据仓库内 frontmatter-reference.md 的说明description命令的简短描述会展示在/help输出中用于说明命令用途argument-hint提示命令可接收的位置参数这里声明为[client_id]表示你可以把 Asana OAuth 应用的 Client ID 作为参数传给/asana-setup。命令的执行约束重要安全提示命令正文有一条明确的硬性约束Do NOT runclaude mcp addyourself — the--client-secretprompt needs a real terminal (a hidden TTY prompt), so the user must run it in their own terminal.也就是说运行/asana-setup时Claude 只会打印配置步骤而不会代为执行claude mcp add。原因在于--client-secret参数不带值时会触发一个隐藏的 TTY 提示符不在对话内回显必须由用户在真实终端中亲自输入 Client Secret。命令文档中还有一处参数占位逻辑若调用时传入了 Client ID即$1非空则打印命令时会自动替换YOUR_CLIENT_ID占位符否则保留占位符等待用户手动替换。这种交互式命令只引导、不代跑的设计正是斜杠命令处理敏感凭据的标准做法。Step 1 — 创建 Asana OAuth 应用一次性在 Asana 开发者控制台 中创建你自己的应用打开 Asana 开发者控制台新建一个应用Create a new app。在应用的OAuth配置区块中添加完全一致的回调地址Redirect URLhttp://localhost:8080/callback复制生成的Client ID和Client Secret稍后使用。为什么回调地址必须是 localhost这一点经常让初次配置者困惑。asana-setup.md 特别说明localhost是正确的不需要改成公网域名。Claude Code 是一个运行在你本机的客户端OAuth 授权码会由本机上的本地监听器local listener捕获因此回调地址设计上就是localhost。你注册的回调端口必须与后面claude mcp add中--callback-port指定的端口完全一致否则授权会失败。再次强调因为 Asana V2 服务器不支持 Dynamic Client Registration你必须自带client_idclient_secret不存在跳过注册的捷径。Step 2 — 添加服务器在你的终端中执行创建好 OAuth 应用后在你自己的终端不要在 Claude 对话内也不要让 Claude 代跑执行以下命令注册 Asana V2 MCP 服务器claude mcp add --transport http \ --client-id YOUR_CLIENT_ID --client-secret \ --callback-port 8080 \ asana https://mcp.asana.com/v2/mcp把YOUR_CLIENT_ID替换为第一步获取的 Client ID。关键参数逐一拆解参数取值含义与注意事项--transport http固定值指定 MCP 传输层为 Streamable HTTP。本仓库 remote-http-scaffold.md 中给出了同一模式的服务端对接方式claude mcp add --transport http name url即可直接连接远程 HTTP MCP 服务器无需本地安装任何服务--client-id你的 Client IDOAuth 客户端标识替换掉YOUR_CLIENT_ID占位符--client-secret不带值该参数后面不跟任何值会触发隐藏提示符将 Client Secret 粘贴进去即可。凭据会被存入操作系统钥匙串OS keychain永远不会以明文写盘--callback-port8080本地 OAuth 回调端口必须与第一步注册的http://localhost:8080/callback中的端口一致asana服务器名称在 Claude Code 中注册的 MCP 服务器别名后续/mcp面板中以该名称显示https://mcp.asana.com/v2/mcpURLAsana V2 MCP 服务器端点凭据存储原理--client-secret无值形式的背后逻辑是Claude Code 会在一个隐藏的 TTY 提示符中读取秘密输入并将结果安全地存入操作系统钥匙串。相比把密钥明文写在命令行或配置文件里这种方式避免了凭据落盘风险。整个注册过程是一次性的之后每次使用 Asana 服务器时都会自动复用这套 OAuth 凭据。Step 3 — 认证与验证服务器注册完成后还需要完成一次 OAuth 授权与连通性验证首次使用触发浏览器授权第一次调用asana服务器时Claude Code 会自动打开浏览器跳转到 Asana 的授权同意页点击批准即可完成 OAuth 授权流程。检查连接状态在 Claude Code 中运行/mcp确认列表中asana显示为connected状态。实际测试向 Claude 提出一个最简单的调用例如list my Asana workspaces列出我的 Asana 工作区验证工具确实可用。典型使用示例连接成功后你可以在日常对话中直接驱动 Asana 的业务操作例如Create an Asana task in the Backend project titled Fix login bug assigned to me.在 Backend 项目中创建任务Fix login bug并分配给我What are my Asana tasks due this week?我本周到期的任务有哪些Search Asana for projects about onboarding.在 Asana 中搜索关于 onboarding 的项目这些能力对应 Asana MCP 服务器的任务创建、项目搜索、任务分配与进度跟踪等工具全部通过自然语言在终端中完成无需离开 Claude Code 会话。故障排查两类高频错误asana-setup.md 与 README.md 共同列出了配置阶段最常出现的两类错误及其处理方式invalid_redirect_uri重定向地址/端口不匹配Asana 应用中的 Redirect URL 必须逐字符一致地为http://localhost:8080/callback--callback-port必须为8080如果你确实想用其他端口那么必须先在 Asana 应用中注册http://localhost:PORT/callback来与之匹配保证两端端口一致。invalid_clientClient ID / Secret 有误检查 Client ID 是否复制正确重新输入 Client Secret可先移除再重加例如执行claude mcp remove asana然后重新运行第 2 步的claude mcp add命令。Auth server / DCR 错误V2 服务器不支持 Dynamic Client Registration。如果看到与 DCR 或认证服务器相关的报错请确认你确实使用了第一步预注册的--client-id与--client-secret而不是期望零配置直连。底层原理补充Streamable HTTP 传输与远程服务器模式从仓库内 remote-http-scaffold.md 的实现可以看出--transport http对应 MCP 的 Streamable HTTP 传输客户端Claude Code通过POST /mcp端点与服务端交换initialize、tools/list、tools/call等 MCP 协议消息。这种模式下的服务器是远程托管的——客户端只需一个 HTTPS URL 即可接入无需在本地安装 Node.js、npm 或任何服务器进程。这正是 Asana V2 的连接形态https://mcp.asana.com/v2/mcp是 Asana 官方托管的端点Claude Code 作为 MCP 客户端通过 HTTP 直连而 OAuth 凭据的作用就是让这个远程端点识别并授权你的个人账号访问权限。理解这条链路后你会更清楚为什么配置的全部重心都落在正确注册 OAuth 应用 让回调端口一致这两件事上。小结配置 Asana V2 MCP 服务器的完整闭环可概括为四步在 Asana 开发者控制台创建 OAuth 应用并注册http://localhost:8080/callback→ 在真实终端中用claude mcp add --transport http注册服务器--client-secret走隐藏提示、凭据入钥匙串→ 浏览器批准授权 → 用/mcp确认 connected 并用一条自然语言指令验证。整个过程只需执行一次之后即可持续在 Claude Code 中管理任务、项目与进度。若遇到invalid_redirect_uri或invalid_client优先核对回调端口一致性与 Client ID/Secret 的正确性即可。如需再次回顾完整流程可随时查阅仓库内的 asana-setup.md 与 README.md或在 Claude Code 中直接运行/asana-setup获取逐步指引。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐连接真实 Host用 python-sdk 将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code连接真实 Host用 python sdk 将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code 本人工智能MCP 服务MCP Clients连接真实 Host用 python-sdk 的 mcp run 命令将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code连接真实 Host用 python sdk 的 mcp run 命令将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor人工智能MCP 服务MCP Clients连接真实宿主用 MCP Python SDK 将服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code连接真实宿主用 MCP Python SDK 将服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code pytho人工智能MCP 服务MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考