做 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 环境依赖清单

建议先确认本机满足这些条件，再开始配置。

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 Secret"

Windows 用户在 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 常见问题速查表

7. 我自己踩过的坑和最后一点经验

这套配置我前后折腾了两轮。第一轮失败在 Windows 命令行格式上，直接把 mac 上的配置复制过去，结果 npx 识别不了。第二轮失败在权限上，子账号只给了常见产品权限，但有个 API 需要额外授权，报错信息又不够明显，最后是一点点加权限试出来的。所以如果你也遇到类似问题，不要怀疑 MCP 概念复杂，绝大多数都是环境、权限、格式这三件事。

我还想特别强调密钥安全。配置里千万不要硬编码 AccessKey Secret，尤其是项目目录如果早晚要提交到代码仓库，那基本等于公开了密钥。即使测试环境也建议用环境变量引用，并且给子账号开启最小权限。另外，MCP 工具虽然方便，但也只是把操作范围限制在授权范围内，不要因为对话式交互就放松对高危操作的控制。

最后分享一个小习惯：每次改完 MCP 配置，我会先用只读查询验证一遍，确认服务在线、工具列表正常、权限足够，再逐步尝试有副作用的操作。这套流程看起来很基础，但真的能帮你省掉后面大量的排障时间。希望这篇教程能让你少走点弯路。