Claude Code MCP配置教程：完整安装与自定义Server开发

Q: Q: MCP 配置后 Claude Code 启动变慢了怎么办？

A: 每个 MCP Server 启动时需要初始化。如果你配了 5 个以上的 Server，启动可能需要额外 3 5 秒。解决方案：(1) 移除不常用的 Server；(2) 使用项目级配置，只加载当前项目需要的工具；(3) 使用 SSE 远程服务，避免本地启动进程。关于 Claude Code 的更多优化技巧，参考 Claude Code 完整配置教程。

Q: Q: 国内网络环境下 npx 下载 MCP 包很慢？

A: 设置 npm 国内镜像： npm config set registry https://registry.npmmirror.com/ 。或者提前全局安装 MCP Server 包： npm install g @modelcontextprotocol/server github ，然后在配置中使用 github 代替 npx y @modelcontextprotocol/server github 。

Claude Code MCP配置全流程教程。涵盖MCP协议原理、命令行添加Server、JSON手动配置、常用Server推荐、权限管理、常见报错排查，以及自定义MCP Server开发。附实战案例和性能优化建议。

适合人群

已安装 Claude Code，想通过 MCP 扩展其能力的开发者
想让 Claude Code 连接外部工具（数据库、浏览器、文件系统等）的用户
遇到 MCP 配置报错，需要排查方案的开发者
想了解 MCP（Model Context Protocol）协议原理的技术人员

准备清单

Claude Code 已安装（npm install -g @anthropic-ai/claude-code）
Node.js 18+ 环境
基本的命令行操作能力
了解 JSON 配置文件格式

什么是 MCP？为什么 Claude Code 需要它

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，让 AI 模型能安全地连接外部工具和数据源。

简单理解： MCP 就像 Claude Code 的"USB 接口"。没有 MCP，Claude Code 只能操作本地文件和终端。有了 MCP，它可以连接数据库、调用 API、操作浏览器、查询 GitHub 等几乎所有外部服务。

MCP 的三大核心概念：

MCP Server — 提供工具/资源的服务端（比如一个 GitHub MCP Server 提供 PR 管理工具）
MCP Client — 调用工具的客户端（Claude Code 本身就是 MCP Client）
Transport — Client 和 Server 之间的通信方式（stdio 或 SSE）

MCP 配置文件位置

Claude Code 的 MCP 配置存放在两个位置：

全局配置（所有项目生效）

# macOS / Linux
~/.claude/settings.json

# Windows
%APPDATA%\claude\settings.json

项目级配置（只对当前项目生效）

# 在项目根目录下
.claude/settings.json

优先级： 项目级配置覆盖全局配置。

配置方法一：命令行添加 MCP Server（推荐）

最简单的方式，直接在 Claude Code 中输入命令：

添加 stdio 类型的 MCP Server

# 语法
claude mcp add <server-name> -s user -- <command> [args...]

# 示例：添加 GitHub MCP Server
claude mcp add github -s user -- npx -y @modelcontextprotocol/server-github

# 示例：添加文件系统 MCP Server
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

# 示例：添加 PostgreSQL MCP Server
claude mcp add postgres -s user -- npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost:5432/dbname

# 示例：添加 Brave Search MCP Server
claude mcp add brave-search -s user -e BRAVE_API_KEY=your-api-key -- npx -y @modelcontextprotocol/server-brave-search

添加 SSE 类型的 MCP Server

# 语法（SSE 远程服务）
claude mcp add --transport sse <server-name> <sse-url>

# 示例：添加远程 MCP 服务
claude mcp add --transport sse remote-api https://mcp.example.com/sse

`-s` 参数说明

值	作用	配置文件位置
`user`	全局生效（推荐）	`~/.claude/settings.json`
`project`	仅当前项目	`.claude/settings.json`

配置方法二：手动编辑 JSON 配置文件

适合批量配置或需要精细控制的场景：

// ~/.claude/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {}
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_your_key_here"
      }
    },
    "remote-service": {
      "type": "sse",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

常用 MCP Server 推荐（2026 年精选）

开发工具类

MCP Server	功能	安装命令
GitHub	PR/Issue/仓库管理	`npx -y @modelcontextprotocol/server-github`
Filesystem	文件系统操作	`npx -y @modelcontextprotocol/server-filesystem /path`
PostgreSQL	数据库查询	`npx -y @modelcontextprotocol/server-postgres <connection-string>`
SQLite	SQLite 操作	`npx -y @modelcontextprotocol/server-sqlite --db-path /path/db.sqlite`
Docker	容器管理	`npx -y @modelcontextprotocol/server-docker`

搜索与信息类

MCP Server	功能	安装命令
Brave Search	网络搜索	`npx -y @modelcontextprotocol/server-brave-search`
Fetch	网页抓取	`npx -y @modelcontextprotocol/server-fetch`
Memory	知识图谱记忆	`npx -y @modelcontextprotocol/server-memory`
Puppeteer	浏览器自动化	`npx -y @modelcontextprotocol/server-puppeteer`

效率工具类

MCP Server	功能	安装命令
Slack	消息管理	`npx -y @modelcontextprotocol/server-slack`
Google Drive	文件管理	`npx -y @modelcontextprotocol/server-gdrive`
Notion	笔记管理	`npx -y @notionhq/notion-mcp-server`
Sequential Thinking	深度思考	`npx -y @modelcontextprotocol/server-sequential-thinking`

MCP 授权与权限管理

查看已配置的 MCP Server

# 列出所有 MCP Server
claude mcp list

# 查看某个 Server 的详情
claude mcp get github

删除 MCP Server

# 删除指定 Server
claude mcp remove github

# 删除项目级配置中的 Server
claude mcp remove -s project github

工具审批机制

Claude Code 对 MCP 工具有审批机制。首次调用某个 MCP 工具时，会弹出确认：

⚡ GitHub MCP Server wants to use: list_commits
   Allow? [Y/n/always]

Y — 本次允许
n — 拒绝
always — 永久允许该工具（不再确认）

管理已授权的工具：

# 查看 MCP 工具授权状态
claude config get mcpApprovedTools

# 重置所有授权（重新审批）
claude config set mcpApprovedTools {}

常见报错与排查

报错一：`MCP server failed to start`

原因： MCP Server 的启动命令执行失败，通常是 Node.js 环境问题或包不存在。

排查步骤：

# 1. 确认 Node.js 版本
node --version  # 需要 18+

# 2. 手动运行 MCP Server 命令看报错
npx -y @modelcontextprotocol/server-github
# 如果报 "command not found"，说明 npx 不在 PATH 中

# 3. 检查网络（npx 需要下载包）
npm config get registry
# 如果是内网环境，设置镜像：
npm config set registry https://registry.npmmirror.com/

# 4. 清理缓存重试
npm cache clean --force

报错二：`MCP tool not found: xxx`

原因： MCP Server 启动了但提供的工具名和你调用的不一致。

排查步骤：

# 查看某个 MCP Server 提供的所有工具
claude mcp get <server-name>

# 确认工具名大小写正确（MCP 工具名区分大小写）

报错三：`ECONNREFUSED` 或连接超时

原因： SSE 类型的远程 MCP Server 无法连接。

排查步骤：

# 1. 测试 URL 是否可访问
curl -v https://mcp.example.com/sse

# 2. 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 3. 如果需要代理，在 MCP 配置中设置环境变量
{
  "mcpServers": {
    "remote": {
      "type": "sse",
      "url": "https://mcp.example.com/sse",
      "env": {
        "HTTP_PROXY": "http://127.0.0.1:7890",
        "HTTPS_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}

报错四：`Authentication required` 或 401 错误

原因： MCP Server 需要 API Key 但未配置或配置错误。

排查步骤：

# 确认环境变量是否设置
claude mcp get <server-name>
# 查看 env 部分的 API Key 是否正确

# 重新设置带 API Key 的 MCP Server
claude mcp remove <server-name>
claude mcp add <server-name> -s user -e API_KEY=your-key -- npx -y @server/package

报错五：`spawn npx ENOENT`

原因： Claude Code 启动 MCP Server 时找不到 npx 命令。常见于通过桌面应用或非标准 shell 启动 Claude Code 的情况。

解决方案：

# 找到 npx 的完整路径
which npx
# 例如输出：/usr/local/bin/npx

# 使用完整路径配置 MCP Server
{
  "mcpServers": {
    "github": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

实战案例：配置完整开发环境

以下是一个前端开发者的完整 MCP 配置示例：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxx"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

配置完成后，你可以这样使用 Claude Code：

你: 帮我在 GitHub 上创建一个新仓库叫 my-project，然后初始化 Next.js 项目

Claude: 
1. [调用 github MCP] 创建仓库 my-project ✓
2. [调用 filesystem MCP] 在 /home/user/projects/my-project 初始化 Next.js ✓
3. [调用 github MCP] 推送初始代码 ✓

想了解 Claude Code 的更多高级用法？看 Claude Code 完整配置教程。

MCP 与 Claude Code 的性能优化

减少 MCP Server 数量

每个 MCP Server 都是一个独立进程，会占用内存和启动时间。建议只配置你实际使用的 Server。

# 查看当前配置了多少个 MCP Server
claude mcp list | wc -l

# 移除不常用的
claude mcp remove unused-server

使用项目级配置隔离

不同项目需要不同的 MCP 工具，使用项目级配置避免全局混乱：

# Web 项目：只需要 github + filesystem
cd ~/projects/web-app
claude mcp add -s project github -- npx -y @modelcontextprotocol/server-github

# 数据项目：需要 postgres + brave-search
cd ~/projects/data-pipeline
claude mcp add -s project postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/analytics

SSE 远程服务 vs stdio 本地服务

对比项	stdio（本地）	SSE（远程）
启动速度	快（本地进程）	需要网络连接
稳定性	高	受网络影响
资源占用	占用本地内存	不占本地资源
适用场景	开发工具、数据库	云服务 API、团队共享

MCP 协议进阶：自定义 MCP Server

如果你想创建自己的 MCP Server，只需实现协议规定的接口：

// 最简 MCP Server 示例（TypeScript）
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-tool", version: "1.0.0" });

// 注册一个工具
server.tool(
  "calculate",                    // 工具名
  "Perform a calculation",        // 描述
  { expression: z.string() },     // 参数 schema
  async ({ expression }) => {     // 处理函数
    const result = eval(expression); // 示例，实际请用安全的方式
    return { content: [{ type: "text", text: String(result) }] };
  }
);

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

然后在 Claude Code 中注册：

claude mcp add my-tool -s user -- node /path/to/my-mcp-server.js

常见问题

Q: MCP 配置后 Claude Code 启动变慢了怎么办？

A: 每个 MCP Server 启动时需要初始化。如果你配了 5 个以上的 Server，启动可能需要额外 3-5 秒。解决方案：(1) 移除不常用的 Server；(2) 使用项目级配置，只加载当前项目需要的工具；(3) 使用 SSE 远程服务，避免本地启动进程。关于 Claude Code 的更多优化技巧，参考 Claude Code 完整配置教程。

Q: MCP 工具调用了但 Claude 说"无法执行"？

A: 检查几个可能的原因：(1) 工具是否被授权——首次使用需要你点击确认；(2) MCP Server 是否正常运行——用 claude mcp list 查看状态；(3) API Key 是否正确——敏感操作需要有效的认证信息。

Q: 国内网络环境下 npx 下载 MCP 包很慢？

A: 设置 npm 国内镜像：npm config set registry https://registry.npmmirror.com/。或者提前全局安装 MCP Server 包：npm install -g @modelcontextprotocol/server-github，然后在配置中使用 github 代替 npx -y @modelcontextprotocol/server-github。

Q: 可以在 Claude Code 的 MCP 中使用 OpenAI 的工具吗？

A: 可以，但需要通过 MCP 协议封装。社区有一些 MCP Server 封装了 OpenAI 的 API（如 DALL-E 图像生成、Whisper 语音转文字）。但更推荐使用 Claude 原生能力，通过 MCP 连接你自己的工具链。想构建更强大的 AI Agent 系统？看 AI Agent 团队协作指南。

Q: MCP 和 Claude Code 的 Hook 系统有什么区别？

A: MCP 是让 Claude Code 连接外部工具的协议（双向通信）。Hook 是 Claude Code 内部的生命周期钩子（单向事件），比如在每次调用工具前后执行自定义脚本。两者互补：MCP 扩展"能做什么"，Hook 控制"怎么做"。详细了解 Hook 系统，看 Claude Code 实战：系统加固。

参考来源

下一步建议

刚接触 Claude Code？先看 Claude Code 完整配置教程
想学 Claude Code 实战开发？看 Claude Code 实战（一）：核心闭环
想了解 AI Agent 的权限和安全？看 Claude Code 实战（二）：系统加固
想对比不同的 AI 编程工具？看 ChatGPT Plus 完整指南

Claude Code MCP 配置完整教程：从安装到自定义 Server 开发

适合人群

准备清单

什么是 MCP？为什么 Claude Code 需要它

MCP 配置文件位置

全局配置（所有项目生效）

项目级配置（只对当前项目生效）

配置方法一：命令行添加 MCP Server（推荐）

添加 stdio 类型的 MCP Server

添加 SSE 类型的 MCP Server

-s 参数说明

配置方法二：手动编辑 JSON 配置文件

常用 MCP Server 推荐（2026 年精选）

开发工具类

搜索与信息类

效率工具类

MCP 授权与权限管理

查看已配置的 MCP Server

删除 MCP Server

工具审批机制

常见报错与排查

报错一：MCP server failed to start

报错二：MCP tool not found: xxx

报错三：ECONNREFUSED 或连接超时

报错四：Authentication required 或 401 错误

报错五：spawn npx ENOENT

实战案例：配置完整开发环境

MCP 与 Claude Code 的性能优化

减少 MCP Server 数量

使用项目级配置隔离

SSE 远程服务 vs stdio 本地服务

MCP 协议进阶：自定义 MCP Server

常见问题

Q: MCP 配置后 Claude Code 启动变慢了怎么办？

Q: MCP 工具调用了但 Claude 说"无法执行"？

Q: 国内网络环境下 npx 下载 MCP 包很慢？

Q: 可以在 Claude Code 的 MCP 中使用 OpenAI 的工具吗？

Q: MCP 和 Claude Code 的 Hook 系统有什么区别？

参考来源

下一步建议

`-s` 参数说明

报错一：`MCP server failed to start`

报错二：`MCP tool not found: xxx`

报错三：`ECONNREFUSED` 或连接超时

报错四：`Authentication required` 或 401 错误

报错五：`spawn npx ENOENT`