教程

Claude Code MCP 集成完全指南：连接外部工具、配置服务器与调试技巧

Claude Code MCP 完整集成指南：stdio 和 HTTP 两种服务器类型配置、常用 MCP 服务器推荐（GitHub/PostgreSQL/Slack/Linear）、在 Subagent 中限制 MCP 访问、Hook 中使用 MCP 工具名匹配、成本优化策略，以及自定义 MCP 服务器开发示例。

2026/2/285分钟 阅读ClaudeEagle

Model Context Protocol（MCP）是让 Claude Code 与外部工具和服务交互的标准协议。通过 MCP，Claude 可以直接访问数据库、调用 API、操作文件系统，乃至控制浏览器——将 AI 的能力与现实世界的工具无缝连接。

什么是 MCP？

MCP 是一个开放协议，标准化了 AI 模型与外部工具之间的通信方式。可以把它理解为 AI 工具的「USB 接口」——任何按照 MCP 规范实现的工具，都可以直接接入 Claude Code，无需定制集成。

MCP 的工作方式：

  1. MCP 服务器以工具定义的形式声明其能力
  2. Claude Code 在启动时发现并加载这些工具
  3. Claude 在需要时调用工具，获取结果并继续工作

快速添加第一个 MCP 服务器

方法一：通过 /mcp 命令

bash
> /mcp
# 选择「添加新服务器」
# 输入服务器名称和启动命令

方法二：直接编辑 .mcp.json

在项目根目录创建 .mcp.json：

json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/your-username/projects"]
    }
  }
}

方法三：HTTP 型 MCP 服务器

json
{
  "mcpServers": {
    "pipedream": {
      "type": "http",
      "url": "https://mcp.pipedream.net/v2"
    }
  }
}

常用 MCP 服务器推荐

开发工具类

json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost/mydb"]
    },
    "sqlite": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "./database.db"]
    }
  }
}

生产力工具类

json
{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"]
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": { "SLACK_BOT_TOKEN": "xoxb-..." }
    },
    "linear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": { "LINEAR_API_KEY": "lin_api_..." }
    }
  }
}

MCP 服务器作用域

配置文件位置作用域适合场景
~/.claude/mcp.json所有项目个人常用工具（GitHub、Slack）
./.mcp.json当前项目项目特定工具（PostgreSQL、Redis）
~/.claude/settings.json所有项目通过设置文件管理

在 Subagent 中限制 MCP 工具

通过 Subagent 的 mcpServers frontmatter，控制哪个 Subagent 能访问哪些 MCP 服务器：

markdown
---
name: db-analyst
description: 数据库分析专家，只能访问数据库
mcpServers:
  - postgres
  - sqlite
tools: Read, Bash
---

你是数据库分析专家。分析数据库结构和查询性能，提供优化建议。

在 Hooks 中使用 MCP 工具名

MCP 工具在 Hooks 中遵循命名模式 mcp__<server>__<tool>：

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__create_issue",
        "hooks": [{
          "type": "command",
          "command": "./hooks/validate-issue.sh"
        }]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [{
          "type": "command",
          "command": "./hooks/log-writes.sh"
        }]
      }
    ]
  }
}

成本优化：减少 MCP 服务器开销

每个 MCP 服务器都会将工具定义加入上下文，即使处于空闲状态：

bash
# 查看上下文占用情况
> /context

# 禁用未使用的服务器
> /mcp

优先使用 CLI 工具：gh、aws、gcloud 比对应的 MCP 服务器更省上下文，因为它们不添加持久的工具定义。Claude 可以直接通过 Bash 工具运行 CLI 命令。

自动工具搜索：当 MCP 工具描述超过上下文的 10%，Claude Code 自动切换为按需加载模式。

bash
# 降低触发阈值（工具超过 5% 时触发按需加载）
export ENABLE_TOOL_SEARCH=auto:5

常见 MCP 使用场景

场景 1：自动化代码审查流程

> 用 GitHub MCP 获取 PR #142 的改动， 然后进行安全审查， 将发现作为 PR 评论发布

场景 2：数据库辅助开发

> 用 Postgres MCP 查看 users 表的结构， 然后生成一个 API 端点来处理用户注册， 包括适当的数据验证和错误处理

场景 3：��工具工作流

> 从 Linear MCP 获取本周的 Sprint 任务， 对每个任务检查对应的 GitHub 分支状态， 生成一份进度报告发到 Slack

调试 MCP 连接

bash
# 检查 MCP 服务器状态
> /mcp

# 查看 MCP 工具列表
> /context  # 查看哪些工具在上下文中

# 测试 MCP 工具
> 列出可用的 github MCP 工具
> 用 github MCP 列出我最近的 5 个 PR

常见问题：

  • 服务器启动失败：检查命令路径和环境变量
  • 认证失败：确认 API Token 格式正确
  • 工具不出现：重启 Claude Code 重新加载 MCP 配置

自定义 MCP 服务器开发

用 Node.js 快速创建自定义 MCP 服务器：

typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'my-custom-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'get_company_data',
    description: '获取公司内部数据',
    inputSchema: {
      type: 'object',
      properties: { department: { type: 'string' } },
      required: ['department']
    }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'get_company_data') {
    const { department } = request.params.arguments;
    // 实现你的业务逻辑
    return { content: [{ type: 'text', text: `${department} 部门数据...` }] };
  }
});

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

原文：MCP - Claude Code Docs | 来源：Claude Code 官方文档