做 AI 辅助开发的朋友应该都有同一个痛点模型再聪明也摸不到你的真实系统。我在 VS Code 里用 Claude Code 写代码时经常要停下来复制粘贴云厂商控制台里的信息或者在代码里临时写一段脚本去调 API。后来把 Claude Code for VS Code 对接上阿里云 MCP 工具之后这条链路才算真正打通。Claude Code 可以直接通过 MCP 协议调用阿里云 OpenAPI查实例、列存储、读配置、做资源巡检都能用自然语言完成。这篇教程就是我从零到一完成这个配置的过程包括为什么这样做、三种接入方式怎么选、配置文件怎么写、启动后怎么验证、以及我在实际使用中踩过的坑。适合正在用 VS Code 写代码、做 DevOps、或者想给 AI 工具接上云服务能力的开发者。前置要求不高有 Node.js 环境、一个阿里云账号、以及耐心读完本文的时间就能动手。1. 先搞清楚 MCP 在这里面到底扮演什么角色很多人一看到 MCP 就以为是某个云厂商专用的插件其实不是。MCP 的全称是 Model Context Protocol是一套开放协议目的是让 AI 应用能够以标准化方式接入外部工具和数据源。放到这个教程的场景里Claude Code 是协议里的“主机”阿里云 MCP Server 是协议里的“服务端”两边通过 JSON-RPC 消息通信。简单说就是给 Claude Code 装了一个可以理解自然语言指令的外接工具层。1.1 MCP 的三种角色MCP 架构里通常有三个角色宿主应用、MCP 客户端、MCP Server。宿主应用就是 Claude Code 所在的 VS Code 环境MCP 客户端负责跟 Server 建立连接、发送请求、接收结果MCP Server 负责把具体业务能力封装成一个个可以被模型调用的工具。阿里云 MCP Server 做的事情是把阿里云的 OpenAPI 封装成工具比如“查询云服务器列表”“创建快照”“检查存储桶状态”等每个工具都有明确的输入参数和返回结构。你可以把 MCP 理解成一个翻译层。以前想让 AI 操作云资源要么在代码里写死 HTTP 请求要么让 AI 输出一段脚本你自己再拿去执行。现在不用了AI 在对话过程中发现用户需要查资源就会主动选择一个名叫“查询云服务器列表”的工具带上必要的参数发起调用然后把返回结果拿回对话里继续推理。整个过程用户看到的是“它会用工具了”底层则是标准的协议交互。1.2 阿里云 MCP 能带来什么实际能力配置完成以后最直观的感受是省掉了大量“打开浏览器、登录控制台、一层层点菜单”的操作。比如我想知道当前账号下有哪些云服务器在运行直接对 Claude Code 说一句“帮我查一下当前账号的云服务器列表只返回实例名称和状态”它会自动调用对应的云 API 并整理结果。再比如脑子一热想批量给某些磁盘打快照也可以让 AI 帮你列出符合条件的磁盘确认后再交给它执行。查询、读取、甚至部分可控的运维操作都能在这个对话链路里完成。这类能力在项目排障、资源盘点、自动化测试环境准备这些场景里非常实用。以前写一个排障脚本可能要半小时现在一句话把资源状态拉出来AI 再结合代码上下文判断问题可能在哪效率确实不一样。1.3 为什么直接用 MCP 而不是自己封装 SDK自己封装 SDK 也能达到类似效果但问题在于每换一个 AI 工具或编辑器就要重写一次。MCP 是开放标准配置一次之后只要宿主应用支持 MCP同样的工具就能复用。而且 MCP Server 本身就是独立进程或远程服务不依赖特定的 IDE不依赖特定的模型也不把密钥逻辑写死在某个项目里。加上阿里云 MCP Server 已经帮你完成了 OpenAPI 的参数映射、鉴权、返回值标准化比自己写几百行胶水代码靠谱太多。2. 配置前要做好的准备别急着改代码这一步最容易翻车。很多人拿到教程直接把配置粘贴进去结果启动时报错又不知道问题出在哪。实际上配置前只要花十分钟检查四样东西后面会非常顺。2.1 环境依赖清单建议先确认本机满足这些条件再开始配置。依赖项建议版本用途VS Code稳定版尽量保持最新承载 Claude Code 扩展Claude Code 扩展最新版MCP 宿主环境Node.js18 及以上运行 MCP Server 进程npm / npx随 Node.js 安装启动 npm 包形式的 MCP Server阿里云账号已实名认证获取访问凭证Node.js 版本太旧是最常见的问题。MCP Server 是 Node.js 进程很多新版本协议实现用了较新的语法Node 16 以下很容易出现加载失败。你可以在终端里输入node -v和npm -v确认版本低于 18 的话建议先升级。2.2 创建最小权限的 AccessKey这一步很多人嫌麻烦直接用了主账号的 AccessKey我强烈不建议这样做。主账号密钥权限过大一旦泄露整个账号的资源都暴露了。正确做法是在阿里云控制台创建 RAM 子用户只给子用户分配需要的权限比如你只需要查询云资源那就只给只读权限不需要给它删除或修改权限。具体创建路径大致是控制台里找到 RAM 访问控制创建用户选择“编程访问”然后给该用户添加权限策略。刚开始做实验的话可以先用一个范围最小的只读策略比如云服务器只读权限、存储只读权限。这样即使密钥不小心被提交到代码仓库攻击者能做的事情也有限。2.3 在 VS Code 里安装并打开 Claude Code 扩展确认环境没问题后在 VS Code 的扩展市场里搜索 Claude Code安装并登录。登录成功后最好在一个项目目录里打开 VS Code因为 MCP 配置有时是按项目加载的。我这里建议新建一个测试目录或者直接在你日常项目里先跑通最小配置不要一上来就给所有项目配。3. 阿里云 MCP 工具的三种接入方式我最后选了哪种阿里云 MCP Server 可以按不同方式接入 Claude Code常见的有三种npm stdio 本地进程方式、HTTP 托管端点方式、以及通过 CLI 命令注册的方式。三者最终都会写进 MCP 配置文件但适用场景区别很大。3.1 方式一npm 包 stdio 本地进程这是我最推荐的方式。本地运行一个 Node.js 进程Claude Code 通过标准输入输出和它通信MCP Server 进程再去调用阿里云 OpenAPI。优点是延迟低、配置直观、密钥不经过第三方服务缺点是需要本机装好 Node.js 环境。配置时命令通常是npx加上 MCP Server 的 npm 包名。以阿里云官方维护的 MCP 包为例配置结构大致是这样{ mcpServers: { aliyun: { type: stdio, command: npx, args: [-y, alibabacloud/mcp-server], env: { ALIBABA_CLOUD_ACCESS_KEY_ID: ${ALIBABA_CLOUD_ACCESS_KEY_ID}, ALIBABA_CLOUD_ACCESS_KEY_SECRET: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET}, ALIBABA_CLOUD_REGION_ID: cn-hangzhou } } } }注意这里env里的变量名可能随官方包版本变化具体以你查到的官方文档为准。我只是用常见命名方式展示参数结构。密钥不建议直接硬编码在配置文件里更推荐在系统环境变量中配置好然后在 JSON 里用${变量名}引用。3.2 方式二HTTP 托管端点如果你不想在本机维护 Node.js 进程或者希望多个开发者共用同一个 MCP Server可以考虑 HTTP 托管端点方式。阿里云会在你开通 MCP 服务后提供一个访问地址配置时只需要在 MCP 配置里填端点 URL 和鉴权信息。这种方式的配置结构大体是这样{ mcpServers: { aliyun-http: { type: http, url: https://your-endpoint.example.com/mcp, headers: { Authorization: Bearer your-token } } } }优点是客户端很轻不依赖本地环境适合团队统一管控。缺点是每家服务商的管理方式不同鉴权信息如何传递要看具体文档。如果你只是个人使用我的建议是优先选方式一少一层中间环节排查起来也简单。3.3 方式三通过 CLI 命令注册Claude Code 本身提供了命令行工具可以用命令把 MCP Server 注册到用户级别或项目级别。先打开 VS Code 的终端确认 claude 命令可用然后执行类似下面的命令claude mcp add aliyun -- npx -y alibabacloud/mcp-server需要传环境变量的话可以用--env参数或者先设置好环境变量再执行注册。CLI 方式的好处是操作快不需要手动打开 JSON 文件但可读性不如直接看配置文件适合你熟悉之后再玩。我个人还是习惯直接编辑配置文件因为每次改了什么、改在哪个层级一目了然。4. 在 VS Code 中把阿里云 MCP 接入 Claude Code 的完整实操下面这部分是我实际操作的完整过程。按照这个顺序走基本不会漏掉关键环节。4.1 找到 MCP 配置文件的入口在 VS Code 里配置 MCP通常有几个入口一个是 Claude Code 扩展的命令面板搜索类似“Claude: Open MCP Config”的命令另一个是项目根目录下手动创建或编辑.mcp.json文件还有一种是编辑用户级配置文件让所有项目都能加载。用户级配置适合你希望全局使用阿里云 MCP 工具的情况项目级配置适合只在某个模块或某个环境里使用。权限隔离角度我更推荐先做项目级配置跑通之后确实需要全局生效再复制到用户级。配好后重启 VS Code 窗口让扩展重新加载配置。4.2 写好最小可运行配置如果你选 npm 方式我建议用一套“能跑、够简单、好排查”的初始配置不要把一堆暂时用不到的工具全部塞进去。先只配置一个阿里云 MCP Server环境变量先指向一个只读授权账号。下面是一个实际能用的例子兼容 macOS 和 Linux{ mcpServers: { aliyun: { type: stdio, command: npx, args: [-y, alibabacloud/mcp-server], env: { ALIBABA_CLOUD_ACCESS_KEY_ID: ${ALIBABA_CLOUD_ACCESS_KEY_ID}, ALIBABA_CLOUD_ACCESS_KEY_SECRET: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET} } } } }Windows 用户需要注意npx不是直接的应用程序名在 Windows 下最好写成这样{ mcpServers: { aliyun: { type: stdio, command: cmd, args: [/c, npx, -y, alibabacloud/mcp-server], env: { ALIBABA_CLOUD_ACCESS_KEY_ID: ${ALIBABA_CLOUD_ACCESS_KEY_ID}, ALIBABA_CLOUD_ACCESS_KEY_SECRET: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET} } } } }不然你会遇到“无法识别 npx”之类的报错。这是我见过最多的新手问题了。4.3 配置环境变量为了避免密钥被写进 JSON 文件建议先把 AccessKey 设置到系统环境变量里。macOS 和 Linux 可以在 shell 配置文件里加export ALIBABA_CLOUD_ACCESS_KEY_ID你的AccessKey ID export ALIBABA_CLOUD_ACCESS_KEY_SECRET你的AccessKey SecretWindows 用户在 PowerShell 里可以用$env:ALIBABA_CLOUD_ACCESS_KEY_ID你的AccessKey ID $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET你的AccessKey Secret设置好之后一定要重新打开 VS Code因为扩展启动时读取的是当时的环境变量。直接在旧窗口里刷新配置经常不生效关掉再开最稳妥。4.4 验证 MCP 工具是否加载成功配置完成并重启窗口后先确认工具列表里有没有阿里云相关工具。你可以打开 Claude Code 的会话面板输入一个最简单的指令请查看当前 MCP 工具列表把阿里云相关的工具名展示给我。如果工具加载成功你会看到类似aliyun_query_instances、aliyun_list_buckets之类的命名。另一个更直接的验证方式是在终端里执行claude mcp list这个命令会输出当前已经注册的 MCP Server 列表看到aliyun就说明接入成功。如果这里的列表正常但对话里看不到工具一般是 VS Code 扩展缓存问题重启窗口即可。4.5 用一次性查询验证连通性工具列表有显示不代表真正能调用成功还要做一次真实调用。我会用一句明确的需求去测试调用阿里云 MCP 工具帮我查询当前账号下的云服务器列表只要实例 ID、名称和运行状态按区域分组展示。Claude Code 会自动选择对应的工具并执行。如果返回结果正常说明网络、鉴权、API 权限都打通了。如果报权限错误请优先检查 RAM 子账号有没有对应授权而不是怀疑配置有问题。5. 把 MCP 用在工作流里的典型场景配置好只是开始真正体现价值的还是具体场景。分享一下我实际用得最多的几种方式。5.1 日常云资源巡检以前巡检要写脚本或者手动登录控制台逐个区域看。现在我会直接让 Claude Code 定期帮我拉取资源清单比如“把当前账号所有地域的云服务器实例列出来只显示运行中且 CPU 使用率超过 80% 的。”虽然 MCP 工具本身不做聚合分析但 Claude Code 作为宿主可以拿到返回数据后做二次整理输出一个清爽的清单。这种使用方式适合每天早上花一分钟快速确认线上资源状态。需要注意的是只读操作比较安全但如果你要让它执行重启、释放实例等写操作必须让它在执行前跟你确认。5.2 把云资源信息直接带入代码上下文写代码的时候很多逻辑依赖真实环境信息比如数据库实例地址、存储桶名称、地域信息。以前要来回切换文档和代码现在可以让 Claude Code 直接通过 MCP 查出来再把信息用于代码生成。比如让 AI 根据某个数据库实例的规格生成一套连接配置或者查一下某个存储桶的访问权限并生成对应的代码注释。这会大幅减少“因为信息不对称导致生成代码脱离实际”的问题。当然敏感信息进出大模型上下文这件事需要自己评估但技术路径上确实方便很多。5.3 结合 MCP 结果做自动化处理还有一种玩法是让 Claude Code 读取 MCP 返回结果后结合代码仓库里的工具函数做更多事。比如查出所有没有打标签的云资源然后生成一份标记清单或者查出磁盘使用率过高的实例再根据代码里的告警模板生成告警消息。整个过程仍然是对话式的但背后已经是一条“数据获取 逻辑处理 结果输出”的链路。6. 常见问题与排查技巧实录这部分全是真实踩坑记录。如果你配置后不顺利先对着表格排查。6.1 MCP 配置了但工具列表不显示原因通常是配置没有重新加载。Claude Code 扩展对配置文件的变更不会自动热更新必须在修改后重启 VS Code 窗口。先确认配置文件语法正确再确认mcpServers这个键名没有写错。最笨但最有效的办法是删除配置后重启一次确认工具消失再重新加配置并重启对比差异。检查顺序建议是npx命令能不能单独执行成功 - 环境变量是否已注入 -claude mcp list是否显示服务 - 对话里是否能看到工具。6.2 启动 MCP Server 时报“无法加载”“命令找不到”这类报错大部分是 Node.js 环境或 npm 包名问题。先单独执行一遍配置里的命令比如直接跑npx -y alibabacloud/mcp-server看能不能启动。如果单独能跑起来那就是 VS Code 扩展没继承你的环境变量 PATH多见于 mac 上通过图形界面打开 VS Code 的情况。解决办法是在终端里用code .命令打开 VS Code确保它继承 shell 环境。6.3 调用工具时提示权限不足权限不足基本和配置无关是 RAM 子账号授权范围不够。确认子账号已经分配了对应的云产品权限。一开始做测试我建议给一个比实际需求稍大一点的读权限跑通了之后再缩到最小权限这样能区分是配置问题还是权限问题。另外有些云 API 接口还会有额外的 RAM Action 授权光有产品级权限还不够要具体看报错信息里的Action是哪个。6.4 HTTPS 端点方式连接超时如果你用 HTTP 托管端点方式出现超时大概率是网络策略或鉴权头不对。先确认请求地址可以正常访问再看请求头里的鉴权字段有没有被正确读取。本地 npm 方式因为不经过额外端点这类问题会少很多。这也是为什么我建议个人使用优先选本地进程。6.5 常见问题速查表现象可能原因快速处理工具列表没有阿里云 MCP配置未重载或文件路径不对重启 VS Code检查配置位置启动报 npx 找不到Windows 命令格式不对使用cmd /c npx提示 InvalidAccessKeyId环境变量未生效重新打开 VS Code检查变量名提示 ForbiddenRAM 权限不足在 RAM 控制台补充对应授权HTTP 端点超时鉴权头或网络策略异常改用本地 npm 方式测试单个工具调用失败包版本更新导致参数变化更新包版本查变更日志7. 我自己踩过的坑和最后一点经验这套配置我前后折腾了两轮。第一轮失败在 Windows 命令行格式上直接把 mac 上的配置复制过去结果 npx 识别不了。第二轮失败在权限上子账号只给了常见产品权限但有个 API 需要额外授权报错信息又不够明显最后是一点点加权限试出来的。所以如果你也遇到类似问题不要怀疑 MCP 概念复杂绝大多数都是环境、权限、格式这三件事。我还想特别强调密钥安全。配置里千万不要硬编码 AccessKey Secret尤其是项目目录如果早晚要提交到代码仓库那基本等于公开了密钥。即使测试环境也建议用环境变量引用并且给子账号开启最小权限。另外MCP 工具虽然方便但也只是把操作范围限制在授权范围内不要因为对话式交互就放松对高危操作的控制。最后分享一个小习惯每次改完 MCP 配置我会先用只读查询验证一遍确认服务在线、工具列表正常、权限足够再逐步尝试有副作用的操作。这套流程看起来很基础但真的能帮你省掉后面大量的排障时间。希望这篇教程能让你少走点弯路。
