Claude Code MCP配置指南：让AI直连GitHub、数据库和Slack

摘要：网上一大半Claude Code MCP教程都在教你敲claude mcp add github npx @anthropic/mcp-github，然后你会发现npm报错——因为这个包名根本不存在。MCP配置真正的门槛从来不是会不会写TypeScript，而是搞清楚2026年官方早就把GitHub、Sentry、Stripe这些主流服务器换成了远程HTTP接入，命令也必须用--把服务器名和启动命令隔开。把这两件事弄明白，比抄十段过时代码都管用。

保哥团队这两年帮不少外贸独立站做SEO自动化，绕不开一件事：让Claude Code能直接读到Google Search Console的数据、查站点数据库、往GitHub提issue。这些都靠MCP（Model Context Protocol，模型上下文协议）打通。可真上手时才发现，市面流传的配置教程版本太旧，照着敲十有八九装不上。这篇就把2026年的正确装法、三种作用域、四类传输、OAuth登录，到从零写一个自己的服务器，一次讲透，命令全部对着官方文档校过。

MCP到底解决了什么问题？

先说人话。没有MCP之前，你想让AI用到某个外部服务的数据，只有两条路：要么把数据手动复制粘贴进对话框，要么写一堆shell命令让它去抓。前者累，后者脆——接口一变脚本就废。

MCP是一套开放标准，把“AI怎么调用外部工具”这件事标准化了。一个MCP服务器对外暴露三类能力：

• 工具（Tools）：让AI能执行动作，比如建一个GitHub issue、跑一条SQL查询。
• 资源（Resources）：让AI能读取数据，比如数据库表结构、一份文档。
• 提示词模板（Prompts）：预先写好的交互模板，在Claude Code里以斜杠命令的形式出现。

有人会问，那我直接让Claude Code跑curl不也能拿数据吗？能，但差别在三个地方。MCP工具自带明确的参数schema，AI知道每个字段要传什么、是什么类型，不用瞎猜；它能被自动发现，连上服务器后工具列表直接出现在AI面前；它还能跨客户端复用，同一个服务器在Claude Code、Cursor、VS Code里都能用。裸shell命令这三样一样都没有。

举个SEO场景就懂了：接上一个能查PostgreSQL的MCP服务器后，你可以直接问“找出过去90天没产生过订单的客户邮箱”，Claude会自己生成SQL、跑查询、把结果整理出来——你一行代码没写。这种把数据源直接喂给AI的能力，正是搭Claude Code SEO自动化工作流时最值钱的一环。

2026年装一个MCP服务器，正确姿势是什么？

这是全文最该看的一节，因为绝大多数过时教程都栽在这里。

第一个大坑：那些@anthropic/mcp-xxx包名是假的

很多中文教程会让你这么装GitHub服务器：

# ❌ 错误示范：这个包在 npm 上根本不存在
claude mcp add github npx @anthropic/mcp-github

@anthropic/mcp-github、@anthropic/mcp-slack、@anthropic/mcp-postgres、@anthropic/mcp-filesystem……这一整套@anthropic/mcp-开头的包名都是凭空捏造的，npm上一个都搜不到，敲下去只会得到404 Not Found。这是个非常典型的“AI写教程时一本正经编出来的命名”，照抄的人不在少数。

2026年的官方现实是：主流服务早就从“本地npm包”迁到了远程HTTP服务器。你不再需要在本机装任何东西，直接连云端地址即可。对照表如下：

想找更多可用服务器，去Anthropic Directory（claude.ai/directory）翻经过审核的连接器，里面列出的远程服务器都能用一条claude mcp add直接接。比抄博客里的包名靠谱得多。

第二个大坑：命令必须用--隔开

过时教程写的是claude mcp add名称 命令 参数，少了一个关键的双横线--。官方语法长这样：

# 通用语法：所有选项放在服务器名之前，-- 之后才是真正的启动命令
claude mcp add [选项] <名称> -- <命令> [参数...]

记住一条铁律：所有以横线开头的选项（--transport、--env、--scope、--header）必须排在服务器名前面，然后用--把名字和后面要执行的命令彻底隔开。这样做是为了防止Claude自己的参数和服务器的参数打架。几个真实例子：

# 接一个远程 HTTP 服务器（最常用，推荐）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 远程服务器带 Bearer Token
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer 你的GitHub令牌"

# 接一个本地 stdio 服务器，注意 -- 之后才是启动命令
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 带环境变量的本地服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=你的KEY airtable \
  -- npx -y airtable-mcp-server

体会一下：--env、--transport都在名字airtable前面，--后面跟着的npx -y airtable-mcp-server才是真正被拉起来的进程。把顺序搞反，Claude会把服务器的--dsn当成自己的参数去解析，直接报错。

装完怎么管理？

# 列出所有已配置的服务器
claude mcp list

# 看某个服务器的详情（含是否连上、OAuth 是否配好）
claude mcp get github

# 移除一个服务器
claude mcp remove github

# 在 Claude Code 会话里查实时状态（推荐）
/mcp

会话里敲/mcp会弹出一个面板，每个服务器旁边显示它暴露了几个工具、有没有连上、要不要登录。如果一个服务器声明了有工具却一个都没暴露出来，面板会专门标出来——这是排查“连上了却用不了”的第一站。/mcp也是Claude Code斜杠命令体系里最常用的一个。

local、project、user三种作用域该怎么选？

这里又是过时教程的重灾区。很多文章只讲“项目级和用户级”两种，还把默认作用域说成项目级——全错。官方实际上有三种作用域，默认是local而不是project：

怎么选，记三句话：带密钥、不想进版本库的私人配置用local；想让整个团队拉代码就自带同一套工具，用project（它会写进.mcp.json让你提交）；自己天天用、跨所有项目的工具用user。

# 显式指定作用域
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

project作用域生成的.mcp.json是标准格式，长这样：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

有个安全细节要知道：从.mcp.json加载的project服务器，Claude Code第一次用之前会弹窗让你批准。这些待批准的服务器在claude mcp list里显示成⏸ Pending approval。想重置批准记录，跑claude mcp reset-project-choices。

团队共享配置时还有个实用功能：.mcp.json支持环境变量展开，敏感值不必写死。语法是${VAR}（取变量值）和${VAR:-默认值}（没设就用默认）：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

这样团队每人填自己的API_KEY环境变量，配置文件本身不含任何密钥，可以安心提交。注意一点：如果某个必填变量既没设也没给默认值，Claude Code会直接解析失败，所以拿不准的变量记得带上:-默认。

HTTP、stdio、SSE三种传输有什么不同？

传输（transport）决定Claude Code怎么和服务器通信。源教程几乎只讲了本地stdio这一种，结果让人误以为玩MCP必须本机装包。其实2026年的主力是远程HTTP：

• HTTP（远程首选）：连云端服务器最广泛支持的方式，支持OAuth，支持--transport标志。能上HTTP就别用别的。
• SSE（已废弃）：旧的Server-Sent Events传输，官方已标记deprecated，有HTTP就别碰它。
• stdio（本地）：服务器作为本机进程跑，适合需要直接访问本地文件系统或跑自定义脚本的场景，比如本地数据库、Playwright。
• WebSocket：持久双向连接，适合服务器要主动往Claude推事件的场景；但它不支持OAuth，只能走静态Header认证，一般场景用HTTP更稳。

一个容易混的点：在.mcp.json里写JSON配置时，type字段除了http还接受streamable-http作为别名。因为MCP规范官方管这种传输叫streamable-http，你从某个服务器文档里复制过来的配置不用改就能用。

本地stdio服务器还有个贴心设计：Claude Code会在拉起服务器进程时塞一个CLAUDE_PROJECT_DIR环境变量，指向项目根目录。你的服务器代码里读process.env.CLAUDE_PROJECT_DIR（Node）或os.environ["CLAUDE_PROJECT_DIR"]（Python）就能拿到项目根路径，不用依赖当前工作目录去猜。

远程服务器要登录怎么办？

接Sentry、Stripe这类云服务时，绕不开身份认证。Claude Code走的是OAuth 2.0，流程比想象的简单。

当一个远程服务器返回401 Unauthorized或403 Forbidden，Claude Code会自动把它标记成“需要认证”，在/mcp面板里点一下就能走浏览器登录：

# 1. 先把需要认证的服务器加进来
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. 在 Claude Code 会话里敲 /mcp，按提示在浏览器里登录
/mcp

登录成功后，令牌会安全地存进你的系统钥匙串（macOS）或凭据文件里，并自动刷新，不会明文写进配置。想撤销访问，在/mcp菜单里选“Clear authentication”。

有个真实踩坑值得提前知道：如果你给服务器手动配了headers.Authorization，而服务器拒绝了这个Header，Claude Code会直接报“连接失败”，不会自动回退到OAuth流程。这时候要么确认令牌对这个MCP端点有效，要么干脆把Header删掉，让它走OAuth。我见过不少人卡在这里，以为是网络问题，其实是Header和OAuth互相打架。

还有一类服务器不支持自动注册OAuth客户端，加进来会报Incompatible auth server: does not support dynamic client registration。这种得先去服务器的开发者后台注册一个OAuth应用，拿到client ID，再用--client-id和--callback-port配进去。属于进阶场景，常规云服务一般不会遇到。

怎么从零写一个自己的MCP服务器？

现成服务器不够用时，自己写一个其实不难。但这里又有个过时教程坑：SDK包名是@modelcontextprotocol/sdk，不是某些教程里写的@modelcontextprotocol/server，导入路径也是@modelcontextprotocol/sdk/server/mcp.js。装错包名同样是404起步。

最快的路子其实是让Claude帮你搭脚手架。官方有个mcp-server-dev插件：

# 在 Claude Code 会话里装官方脚手架插件
/plugin install mcp-server-dev@claude-plugins-official

# 装完跑构建技能，它会问你的用途，自动生成远程 HTTP 或本地 stdio 服务器
/mcp-server-dev:build-mcp-server

如果想手写练手，一个最简的stdio服务器骨架是这样（注意所有日志都用console.error，下一节会解释为什么）：

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool(
  "my_tool",
  {
    title: "My Tool",
    description: "这个工具是做什么的",
    inputSchema: {
      param: z.string().describe("这个参数是干嘛的，写清楚 Claude 才知道怎么传"),
    },
  },
  async ({ param }) => {
    console.error(`Processing: ${param}`);
    return {
      content: [{ type: "text", text: `Result: ${param}` }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

几条不成文但极重要的设计原则，写之前先记住：

• package.json必须有"type": "module"，否则import语句直接报SyntaxError。
• 每个参数都加.describe()，这是Claude理解工具用途的唯一线索，省略了AI就会乱传。
• 所有工具必须在connect()之前注册完，注册晚了服务器虽然启动但工具列表是空的。
• 所有异步操作用try/catch包住，出错时返回isError: true，不要让它静默崩。

资源（Resources）和提示词（Prompts）也都能往上加。资源在Claude Code里用@server:协议://路径的形式引用，比如@github:issue://123，类似引用文件那样把数据拽进对话；提示词则会变成斜杠命令，格式是/mcp__服务器名__提示词名，能直接在会话里调。

MCP服务器调试为什么总是静默失败？

自己写服务器，十有八九会撞上“服务器启动了，工具却不出现，也没报错”的鬼打墙。九成是同一个原因，记住这条黄金法则：

所有日志只能用console.error，绝对不能用console.log。因为stdio服务器的stdout被JSON-RPC协议消息独占了，你一旦console.log往stdout里写普通文本，就会污染协议流，客户端立刻报Unexpected token然后整个连接崩掉。日志一律走stderr（也就是console.error），stdout留给协议。

其余常见错误对照修复表，照着排查能省一大半时间：

调试时还有几个趁手的招：不连Claude Code也能独立测，用官方的npx @modelcontextprotocol/inspector node dist/index.js起一个可视化检查器，工具能不能调一目了然。具体的协议构建细节，Model Context Protocol官方的构建服务器指南讲得最完整，比任何二手教程都准。

另外注意一个容量限制：当某个MCP工具的输出超过10000 token，Claude Code会弹警告；默认上限是25000 token。如果你的服务器要返回大数据集（比如完整库表结构），可以用MAX_MCP_OUTPUT_TOKENS环境变量调高，或者在服务器端给那个工具标注一个更大的阈值。

MCP配置对SEO和外贸独立站有什么用？

讲了一堆机制，落到生意上才有意义。保哥团队带过的几类客户里，MCP真正用出价值的场景有这么几个，都和这三类人——SEO从业者、外贸运营、独立站站长——直接相关。

一个做美妆DTC的客户，原来每周拉GSC数据、对着Excel找“有曝光没点击”的页面，一个人要花大半天。接上数据库MCP服务器后，把站内文章表、GSC导出表都暴露给Claude Code，直接问“列出曝光大于500但点击率低于1%的页面，按曝光降序”，结果几秒钟出来，还能顺手让它生成改标题的建议。这套思路本质上就是把装好的Claude Code从“写代码的工具”升级成“能直接操作你业务数据的助手”。

另一类是B2B外贸站，用GitHub远程MCP服务器后，发现线上bug直接说一句“给这个分页问题建个issue并指派给我”，Claude就替你建好了，连复制粘贴报错都省了。配合Sentry MCP，还能反过来问“过去24小时最高频的报错是哪些”，把监控数据直接拽进对话里定位问题。

这里有个保哥反复叮嘱客户的安全细节：把生产库接给AI时，务必只给只读权限。自己写数据库MCP服务器的话，在工具里加一道硬校验，非SELECT开头的语句一律拒绝执行，并且数据库账号本身就用只读角色，双保险。曾经有个客户图省事用了带写权限的连接串，虽然没出事，但AI万一被一段恶意的页面内容诱导（也就是提示词注入），生成一条DELETE就麻烦了。读数据是提效，改数据要人盯着，这条线对独立站这种数据即资产的生意尤其要守住。

这里要说句实在话：MCP不是万能的，也不是接得越多越好。每多接一个服务器，都会占用一点上下文。好在2026年的Claude Code默认开了Tool Search——工具定义延迟加载，会话启动时只读服务器名和说明，Claude真要用某个工具时才去搜出来。所以哪怕你接了十几个服务器，对上下文窗口的挤占也很小。这是个对“工具党”特别友好的默认设置。

有哪些容易踩的坑和适用边界？

最后把零散但要命的边界条件集中列一下，每条都是真金白银换来的：

• 安全第一：接任何服务器前确认你信任它。会去抓外部内容的服务器（比如能读网页的）有提示词注入风险，相当于把一个陌生人的输入直接喂给了你的AI。来路不明的服务器别接。
• 名字workspace是保留字：如果你的配置里有个服务器叫workspace，Claude Code会跳过它并警告你改名。
• 同名服务器只连一次：同一个名字在local、project、user多处定义时，优先级从高到低依次是local、project、user、插件、claude.ai连接器，取最高的那份，字段不会跨作用域合并。
• stdio服务器不会自动重连：HTTP/SSE服务器断了会用指数退避自动重连（最多五次），但本地stdio是本机进程，挂了不自动拉起，得手动重来。
• per-server超时是硬墙：在.mcp.json里给某服务器加"timeout"（毫秒）是单次工具调用的硬性时限，服务器发进度通知也不会延长它。长任务记得调大，比如"timeout": 600000给十分钟。
• Claude Code自己也能当MCP服务器：跑claude mcp serve就把Claude Code的工具暴露给别的应用（如Claude Desktop）调用。冷门但偶尔有用。

还有个迁移老用户的福利：如果你早就在Claude Desktop里配好了一堆服务器，不用重配，跑claude mcp add-from-claude-desktop能交互式地把它们导进Claude Code（仅macOS和WSL支持）。已经登录claude.ai账号的话，你在网页端加的连接器也会自动在Claude Code里可用。

关于MCP的全部官方配置细节，Claude Code官方MCP文档是唯一权威来源，命令一变这里第一时间更新；想理解协议本身的设计哲学，去读MCP官方规范介绍页。把这两份当底本，再回头看任何二手教程，过时的、编造的命令你一眼就能识破。MCP配好了，Claude Code才真正从一个写代码的工具，变成能接管你半个业务后台的助手。要把它和自动化进一步串起来，可以再看看怎么用Claude Code Hooks在MCP工具调用前后挂自动化动作。

常见问题解答

MCP和直接调REST API有什么区别？

REST API是给程序调的，你得自己写代码处理认证、解析、错误。MCP是给AI调的标准协议，工具自带参数schema和说明，Claude能自动发现并理解怎么用，还能跨客户端复用。简单说，REST让你的代码会说话，MCP让你的AI会动手。

应该选local、project还是user作用域？

带密钥、不想进版本库的私人配置用local（默认）；想让团队拉代码就自带同一套工具用project，它会写进.mcp.json让你提交；自己跨所有项目天天用的工具用user。拿不准就用默认的local。

远程HTTP服务器和本地stdio服务器怎么选？

能用远程HTTP就优先用，不必本机装包、支持OAuth、最省事，GitHub、Sentry、Stripe都走这条路。只有当工具需要直接访问本地文件、跑本地脚本或本地数据库时，才用stdio，比如本地PostgreSQL或Playwright。

为什么照教程装@anthropic/mcp-github会报错？

因为这个包名是假的，npm上不存在，整套@anthropic/mcp-开头的包都是过时教程编造的。GitHub的正确接法是远程HTTP服务器https://api.githubcopilot.com/mcp/，用GitHub个人访问令牌走Header认证。

一台机器能同时跑多少个MCP服务器？

没有硬性数量上限，挂十几个也行。Claude Code默认开启的Tool Search会延迟加载工具定义，多接服务器对上下文窗口的挤占很小。但每个服务器仍占一点资源，按需接、信任谁接谁，别为了凑数乱接。

MCP服务器能读到我电脑上的哪些文件？

取决于服务器自己声明的能力和你给的权限。文件系统类的本地stdio服务器只能访问你启动时指定的目录；远程HTTP服务器一般碰不到你的本地文件。接服务器前务必确认你信任它，会抓外部内容的服务器还有提示词注入风险。

自己写MCP服务器该用TypeScript还是Python SDK？

两个SDK功能对等，按你团队的技术栈选。TypeScript生态里npm分发和npx直跑更顺手；Python适合数据/科学计算重的服务器。注意TypeScript的SDK包名是@modelcontextprotocol/sdk，别被过时教程里的@modelcontextprotocol/server带偏。