Claude Code MCP 集成实战 — GitHub / PostgreSQL / Puppeteer / 插件市场

简介

Model Context Protocol (MCP) 是 Anthropic 推出的开放标准协议，旨在让 AI 模型与外部工具和数据源进行标准化交互。通过 MCP，Claude Code 可以无缝连接到 GitHub 仓库、PostgreSQL 数据库、浏览器自动化工具等数百种外部服务，极大地扩展了 AI 编程助手的能力边界。

如果说 Claude Code 本身是一个功能强大的 IDE，那么 MCP Server 就是连接外部世界的"插件系统"。通过 MCP，Claude Code 不再是孤立的代码编辑器，而是能够读取 GitHub 上的 Issue、查询数据库中的实时数据、控制浏览器进行测试的综合开发平台。

本文将带你从 MCP 的基础概念出发，深入讲解三种最常用的 MCP Server 的实战集成：GitHub Server（代码仓库管理）、PostgreSQL Server（数据库交互）、Puppeteer Server（浏览器自动化）。你将学会如何安装、配置、调试和使用这些 Server，并将它们集成到 Claude Code 的工作流中。

一、MCP 协议基础
二、MCP Server 安装与配置
三、GitHub MCP Server 实战
四、PostgreSQL MCP Server 实战
五、Puppeteer MCP Server 实战
六、调试与故障排查
七、自定义 MCP Server
八、MCP 审批流程与插件市场（v2.1.154+ 新特性）
九、真实经验与踩坑
十、落地检查清单
十一、总结
十二、下篇预告

一、MCP 协议基础

1.1 什么是 MCP？

Model Context Protocol (MCP) 是一种客户端-服务器协议，定义了 AI 模型与外部工具之间的标准交互方式。其核心思想是：

text

┌─────────────────────────────────────────────────┐
│                  Claude Code                     │
│                  (MCP Client)                    │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ 工具 1   │  │ 工具 2   │  │ 工具 N   │      │
│  │ (Tool)   │  │ (Tool)   │  │ (Tool)   │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │             │             │              │
│  ┌────┴─────────────┴─────────────┴────┐        │
│  │         MCP Client API               │        │
│  └────────────────┬────────────────────┘        │
└───────────────────┼─────────────────────────────┘
                    │ MCP Protocol (JSON-RPC)
                    │
    ┌───────────────┼───────────────┐
    │               │               │
┌───┴───┐     ┌─────┴─────┐   ┌────┴────┐
│GitHub  │     │PostgreSQL │   │Puppeteer│
│Server  │     │Server     │   │Server   │
└───────┘     └───────────┘   └─────────┘
     (MCP Servers)

1.2 核心概念

概念	说明
MCP Client	连接到 MCP Server 的客户端（Claude Code 充当此角色）
MCP Server	提供工具、资源和提示的服务端
Tool	Server 暴露的可执行操作（如 `create_issue`、`query`）
Resource	Server 提供的可读取数据（如文件内容、数据库表）
Prompt	Server 提供的预定义提示模板

1.3 Claude Code 中的 MCP 配置

Claude Code 通过 ~/.claude.json 或项目级 .claude/mcp.json 配置 MCP Server：

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

二、MCP Server 安装与配置

2.1 全局配置 vs 项目配置

全局配置（~/.claude.json）：适用于所有项目

bash

# 编辑全局配置
claude settings

项目配置（.claude/mcp.json）：仅适用于当前项目

bash

mkdir -p .claude
cat > .claude/mcp.json << 'EOF'
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
EOF

2.2 环境变量管理

推荐将敏感信息存储在环境变量中，而不是直接写入配置文件：

bash

# ~/.zshrc 或 ~/.bashrc
export GITHUB_TOKEN="ghp_your_token_here"
export DATABASE_URL="postgresql://user:pass@localhost/dbname"

# 在配置中引用
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

三、GitHub MCP Server 实战

3.1 安装与配置

bash

# 方式 1: 使用 npx（推荐）
# 在 ~/.claude.json 或 .claude/mcp.json 中添加：
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

# 方式 2: 全局安装
npm install -g @modelcontextprotocol/server-github

3.2 获取 GitHub Token

bash

# 1. 访问 https://github.com/settings/tokens
# 2. 点击 "Generate new token" → "Generate new token (classic)"
# 3. 选择以下权限：
#    - repo (完整仓库访问)
#    - read:org (组织读取)
#    - read:user (用户读取)
#    - user:email (邮箱读取)
# 4. 复制 Token 并设置环境变量
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

3.3 可用工具列表

GitHub MCP Server 提供以下工具：

工具	说明
`create_or_update_file`	创建或更新文件
`push_files`	批量推送文件
`search_repositories`	搜索仓库
`create_repository`	创建仓库
`get_file_contents`	获取文件内容
`create_issue`	创建 Issue
`get_issue`	获取 Issue 详情
`list_issues`	列出 Issue
`update_issue`	更新 Issue
`create_pull_request`	创建 PR
`get_pull_request`	获取 PR 详情
`list_pull_requests`	列出 PR
`merge_pull_request`	合并 PR
`get_pull_request_files`	获取 PR 变更文件
`create_pull_request_review`	创建 PR 审查
`list_commits`	列出提交记录

3.4 实战：通过 Claude Code 操作 GitHub

text

用户: 为当前项目创建一个 Issue，标题是 "修复登录页样式问题"

Claude Code:
✅ 已通过 GitHub MCP 创建 Issue #123
   标题: 修复登录页样式问题
   仓库: owner/my-project
   链接: https://github.com/owner/my-project/issues/123

text

用户: 列出当前仓库中所有标记为 "bug" 的开放 Issue

Claude Code:
通过 GitHub MCP 查询结果：
1. #42 - 登录按钮在移动端重叠 [bug]
2. #56 - 搜索框无法清空 [bug]
3. #89 - 深色模式下文字不可读 [bug]
...

text

用户: 创建一个新分支 "fix/login-style" 并修改 src/components/Login.tsx 中的 padding

Claude Code:
1. ✅ 已通过 GitHub MCP 创建分支 "fix/login-style"
2. ✅ 已修改 src/components/Login.tsx (padding: 12px → 16px)
3. ✅ 已通过 GitHub MCP 提交更改
4. ✅ 已创建 PR #130: "fix: 调整登录组件内边距"

3.5 完整工作流示例

bash

# .claude/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

text

用户: 帮我完成一个完整的 GitHub 工作流：
1. 搜索 "typescript best practices" 相关的热门仓库
2. 在我们的仓库中创建一个 Issue 记录调研结果
3. 创建一个 PR 来实施最佳实践

Claude Code 执行:
Step 1: 使用 search_repositories 搜索
Step 2: 汇总搜索结果，创建 Issue
Step 3: 基于调研结果创建 PR

四、PostgreSQL MCP Server 实战

4.1 安装与配置

bash

# 在配置中添加：
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp"
      ]
    }
  }
}

4.2 Docker 快速启动测试数据库

bash

# 启动 PostgreSQL 容器
docker run -d \
  --name postgres-mcp \
  -e POSTGRES_USER=dev \
  -e POSTGRES_PASSWORD=dev123 \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  postgres:16-alpine

# 测试连接
docker exec -it postgres-mcp psql -U dev -d myapp -c "SELECT version();"

# 配置连接字符串
export DATABASE_URL="postgresql://dev:dev123@localhost:5432/myapp"

4.3 可用工具

工具	说明
`query`	执行只读 SQL 查询
`write`	执行写入操作（INSERT/UPDATE/DELETE）

⚠️ 注意：默认情况下，PostgreSQL MCP Server 可能限制写入操作。生产环境中建议使用只读连接字符串。

4.4 实战：数据库查询与分析

text

用户: 查询 users 表中最近 7 天注册的用户数量，按天分组

Claude Code:
通过 PostgreSQL MCP 执行查询：
SELECT DATE(created_at) as day, COUNT(*) as count
FROM users
WHERE created_at >= NOW() - INTERVAL '7 days'
GROUP BY DATE(created_at)
ORDER BY day;

结果：
| day        | count |
|------------|-------|
| 2024-01-15 | 23    |
| 2024-01-16 | 31    |
| 2024-01-17 | 18    |
...

text

用户: 检查 orders 表中是否有孤立的订单（user_id 在 users 表中不存在）

Claude Code:
执行查询：
SELECT o.id, o.user_id
FROM orders o
LEFT JOIN users u ON o.user_id = u.id
WHERE u.id IS NULL
LIMIT 10;

结果: 发现 3 条孤立订单记录。

4.5 实战：数据库 Schema 设计辅助

text

用户: 我需要设计一个博客系统的数据库 schema，请帮我：
1. 创建 users、posts、comments 表
2. 设置正确的外键关系
3. 添加索引

Claude Code:
通过 PostgreSQL MCP 执行：

-- 创建 users 表
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 创建 posts 表
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    status VARCHAR(20) DEFAULT 'draft',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 创建 comments 表
CREATE TABLE comments (
    id SERIAL PRIMARY KEY,
    post_id INTEGER REFERENCES posts(id) ON DELETE CASCADE,
    user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_posts_user_id ON posts(user_id);
CREATE INDEX idx_posts_status ON posts(status);
CREATE INDEX idx_comments_post_id ON comments(post_id);

4.6 只读模式配置（生产推荐）

bash

# 创建只读用户
docker exec -it postgres-mcp psql -U dev -d myapp << 'SQL'
CREATE ROLE readonly_user WITH LOGIN PASSWORD 'readonly123';
GRANT CONNECT ON DATABASE myapp TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;
SQL

# 配置只读连接
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://readonly_user:readonly123@localhost:5432/myapp"
      ]
    }
  }
}

五、Puppeteer MCP Server 实战

5.1 安装与配置

bash

# 首先安装 Chrome/Chromium
# Ubuntu/Debian:
sudo apt-get install -y chromium-browser

# macOS:
brew install --cask chromium

# 配置 MCP Server
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

5.2 可用工具

工具	说明
`puppeteer_navigate`	导航到 URL
`puppeteer_screenshot`	截取屏幕截图
`puppeteer_click`	点击元素
`puppeteer_hover`	悬停在元素上
`puppeteer_fill`	填充表单字段
`puppeteer_select`	选择下拉选项
`puppeteer_evaluate`	执行 JavaScript

5.3 实战：网页截图与检查

text

用户: 帮我截图看看 http://localhost:3000 的首页效果

Claude Code:
通过 Puppeteer MCP 截取屏幕截图:
✅ 已保存截图到 /tmp/screenshot_localhost.png
[截图显示...]

text

用户: 导航到 http://localhost:3000，点击登录按钮，
在用户名框输入 "test@example.com"，密码框输入 "test123"，
然后点击登录，截图看看结果

Claude Code:
Step 1: ✅ 导航到 http://localhost:3000
Step 2: ✅ 点击 "登录" 按钮
Step 3: ✅ 填写用户名: test@example.com
Step 4: ✅ 填写密码: test123
Step 5: ✅ 点击 "登录" 按钮
Step 6: ✅ 截图已保存

5.4 实战：自动化测试辅助

text

用户: 帮我对我们的登录页面做一轮视觉检查：
1. 检查页面加载是否正常
2. 检查表单元素是否都能正常交互
3. 尝试用空表单提交，检查验证提示
4. 用正确的凭据登录，检查跳转

Claude Code:
通过 Puppeteer MCP 执行:

1. ✅ 页面加载成功 (HTTP 200)
   - 页面标题: "登录 - MyApp"
   - 加载时间: 1.2s

2. ✅ 表单元素检查:
   - 用户名输入框: 存在 ✓
   - 密码输入框: 存在 ✓
   - 登录按钮: 存在 ✓
   - "忘记密码" 链接: 存在 ✓

3. ✅ 空表单提交验证:
   - 提交后显示错误提示 ✓
   - "请输入邮箱地址" ✓
   - "请输入密码" ✓

4. ✅ 正确登录测试:
   - 登录成功 ✓
   - 跳转到 /dashboard ✓
   - 显示欢迎信息 "Welcome, Test User" ✓

六、调试与故障排查

6.1 检查 MCP Server 状态

bash

# 启动 Claude Code 后检查 MCP 连接
claude --print
# 查看输出中的 MCP 连接状态

6.2 常见错误与解决方案

错误 1: MCP Server 启动失败

text

错误: Failed to start MCP server "github"
原因: 缺少环境变量 GITHUB_PERSONAL_ACCESS_TOKEN
解决: 设置环境变量或检查配置文件

错误 2: 连接被拒绝

text

错误: Connection refused for postgres MCP server
原因: PostgreSQL 服务未运行或端口不正确
解决:
1. 检查服务状态: docker ps | grep postgres
2. 检查端口: netstat -tlnp | grep 5432
3. 测试连接: psql -h localhost -p 5432 -U dev -d myapp

错误 3: 工具不可用

text

错误: Tool "create_issue" not found
原因: MCP Server 版本过旧
解决: 更新 Server 包
npm install @modelcontextprotocol/server-github@latest

6.3 日志调试

bash

# 启用 MCP 调试日志
export ANTHROPIC_LOG_LEVEL=debug
claude

七、自定义 MCP Server

7.1 创建一个简单的 MCP Server

typescript

// my-mcp-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

// 注册工具
server.tool("greet", { name: z.string() }, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));

server.tool("file-stats", { path: z.string() }, async ({ path }) => {
  const stats = await fs.promises.stat(path);
  return {
    content: [{
      type: "text",
      text: `Size: ${stats.size} bytes, Modified: ${stats.mtime}`,
    }],
  };
});

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

7.2 配置自定义 Server

json

{
  "mcpServers": {
    "my-custom": {
      "command": "npx",
      "args": ["ts-node", "/path/to/my-mcp-server.ts"]
    }
  }
}

八、MCP 审批流程与插件市场（v2.1.154+ 新特性）

Claude Code v2.1.154 引入了 MCP 审批流程和插件市场两个重要特性，让 MCP Server 的管理从“手动配置”进化为“企业级治理”。

8.1 MCP 审批流程

在企业环境中，不是所有 MCP Server 都可以随意接入。审批流程允许管理员控制哪些 MCP Server 可以使用：

json

// .claude/settings.json
{
  "mcpApproval": {
    "enabled": true,
    "allowedServers": [
      "@modelcontextprotocol/server-github",
      "@modelcontextprotocol/server-postgres"
    ],
    "requireApproval": ["*"],
    "approvalEndpoint": "https://api.company.com/mcp/approve"
  }
}

参数说明：

字段	说明
`enabled`	是否启用审批流程
`allowedServers`	已审批的 Server 白名单
`requireApproval`	需要审批的 Server（`["*"]` 表示所有）
`approvalEndpoint`	企业审批服务的 API 地址

8.2 插件市场

Plugin 是 Claude Code 最高级别的扩展方式，可以把 Skill、Subagent、Hook、MCP Server、LSP 配置等打包成一个可安装的插件。只需安装一次，就能自动获得所有配置：

bash

# 安装社区插件
claude plugin install @anthropic/github-workflow-pack

# 查看已安装的插件
claude plugin list

# 查看插件包含的组件
claude plugin info @anthropic/github-workflow-pack
# 输出:
# - Skills: pr-review, issue-triage
# - Agents: @code-reviewer, @security-scanner
# - Hooks: PreToolUse (git protection), PostToolUse (auto-lint)
# - MCP: @modelcontextprotocol/server-github

插件目录结构：

text

my-plugin/
├── plugin.json            # 插件元数据
├── skills/                # Skills
│   └── springboot/
├── agents/                # Sub-Agents
│   └── architect.md
├── hooks/
│   └── hooks.json         # PreToolUse / PostToolUse / Session
└── mcp/
    └── mcp.json           # MCP Server 配置

8.3 踩坑经验

场景：团队成员随意安装未审批的 MCP Server，导致敏感数据泄露
问题：没有审批流程，任何人都可以接入任意 MCP Server
解决方案：启用 mcpApproval，将 MCP Server 纳入企业 IT 治理体系

九、真实经验与踩坑

9.1 经验 1：GitHub Token 权限过宽导致误操作

场景：团队接入 GitHub MCP Server，使用具有完整 repo 权限的 Classic Token
问题：Claude Code 在一次误操作中删除了远程分支，因为 Token 权限过宽无法阻止
解决方案：改用 Fine-grained Token，仅授权 contents: read 和 issues: write 权限，拒绝 contents: write

9.2 经验 2：PostgreSQL 查询拖垮生产数据库

场景：PostgreSQL MCP Server 连接生产数据库，Claude 生成的查询缺少 LIMIT 导致全表扫描
问题：慢查询把数据库打满，其他服务全部超时
解决方案：改为连接只读副本，并在配置中设置 statement_timeout: 30000（30 秒超时），避免长时间查询

十、落地检查清单

MCP Server 配置文件（~/.claude.json 或 .claude/mcp.json）已创建
所有敏感凭证通过环境变量注入，未明文写入配置
生产数据库 Server 仅连接只读副本，设置了 statement_timeout
GitHub Server 的 Token 遵循最小权限原则（Fine-grained Token）
自定义 MCP Server 有错误处理和超时配置
已配置 mcpApproval 审批流程（企业环境）
已验证 Claude Code 可正常调用所有已配置的 MCP 工具
插件市场安装的组件已记录在 .claude/mcp.json 中

十一、总结

MCP 协议为 Claude Code 打开了通往外部世界的大门。通过集成 GitHub、PostgreSQL、Puppeteer 等 MCP Server，Claude Code 从单纯的代码编辑工具升级为全栈开发平台。

关键要点：

MCP 是 AI 模型与外部工具交互的开放标准协议
通过 ~/.claude.json 或 .claude/mcp.json 配置 MCP Server
GitHub Server 让 Claude Code 可以直接操作仓库、Issue 和 PR
PostgreSQL Server 支持实时数据库查询和 Schema 设计
Puppeteer Server 提供浏览器自动化能力
敏感凭证应使用环境变量管理
生产环境建议使用只读连接
可以开发自定义 MCP Server 扩展功能
v2.1.154+ 支持 MCP 审批流程，适配企业 IT 治理
插件市场允许将多个组件打包安装，简化配置管理

十二、下篇预告

Hooks 自动化深度指南 — 探索 Claude Code 的事件钩子系统，掌握 PreToolUse、PostToolUse、Notification 等 10 种钩子类型的配置方法，并学习 HTTP Hooks、异步 Hooks、LLM Prompt Hooks 三种高级特性，实现自动权限审批、操作日志记录、通知推送等高级自动化场景。