第 20 期 | 官方内置连接器配置与启用
🎯 学习目标
学完本期你将掌握：
- Claude Code 内置 MCP Server 的完整配置流程
- GitHub、Postgres、文件系统等官方连接器的实操指南
- 全局 vs 项目级 MCP 配置的选择策略
- 常见配置问题的排查方法
📖 核心概念讲解
20.1 配置的两个层级
层级 1: 全局配置 (User-level)
位置: ~/.claude/settings.json
作用: 所有项目通用的 MCP Server
适合: GitHub、Slack 等个人账号级服务
层级 2: 项目配置 (Project-level)
位置: .mcp.json (项目根目录)
作用: 仅在当前项目中生效
适合: 项目专属的数据库连接、私有 API
⚠️ 首次使用需要 Claude 请求你授权
层级 3: 企业配置 (Enterprise)
位置: 由管理员统一下发
作用: 整个团队共享的 MCP Server
适合: 内部工具平台、合规审查服务
20.2 常见官方 MCP Server
╭────────────────────────────────────────────────╮
│ Anthropic 官方维护: │
│ ├── @anthropic-ai/mcp-server-github │
│ ├── @anthropic-ai/mcp-server-postgres │
│ ├── @anthropic-ai/mcp-server-filesystem │
│ └── @anthropic-ai/mcp-server-memory │
│ │
│ 高质量社区维护: │
│ ├── mcp-server-slack │
│ ├── mcp-server-notion │
│ ├── mcp-server-linear │
│ ├── mcp-server-playwright │
│ ├── mcp-server-puppeteer │
│ └── mcp-server-excalidraw │
╰────────────────────────────────────────────────╯
💻 模拟 Claude TUI 交互
场景 1：配置 GitHub MCP Server
> 我想配置 GitHub 集成，让你能直接操作我的仓库
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ 好的！配置 GitHub MCP Server 需要 3 步: │
│ │
│ 📋 步骤 1: 创建 GitHub Personal Access Token │
│ 访问: github.com/settings/tokens/new │
│ 勾选: repo, issues, pull_requests 权限 │
│ │
│ 📋 步骤 2: 添加 MCP 配置 │
│ ⚙️ Tool: Edit → ~/.claude/settings.json │
│ ╭─ 添加内容 ────────────────────────────────╮ │
│ │ { │ │
│ │ "mcpServers": { │ │
│ │ "github": { │ │
│ │ "command": "npx", │ │
│ │ "args": [ │ │
│ │ "-y", │ │
│ │ "@anthropic-ai/mcp-server-github" │ │
│ │ ], │ │
│ │ "env": { │ │
│ │ "GITHUB_TOKEN": "ghp_xxxxx" │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ ╰────────────────────────────────────────────╯ │
│ │
│ 📋 步骤 3: 重启 Claude Code │
│ 退出并重新运行 `claude` 命令 │
│ │
│ 配置完成后你可以这样使用: │
│ - "列出我所有的 GitHub 仓库" │
│ - "在 my-repo 创建一个 Issue" │
│ - "提交当前改动并创建 Pull Request" │
│ │
╰──────────────────────────────────────────────────────╯
场景 2：配置项目专属的 Postgres MCP
> 这个项目需要连接 Postgres 数据库进行查询
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ 项目级数据库连接适合放在 .mcp.json: │
│ │
│ ⚙️ Tool: Write → .mcp.json │
│ ╭─ 文件内容 ────────────────────────────────╮ │
│ │ { │ │
│ │ "mcpServers": { │ │
│ │ "postgres": { │ │
│ │ "command": "npx", │ │
│ │ "args": [ │ │
│ │ "-y", │ │
│ │ "@anthropic-ai/mcp-server-postgres"│ │
│ │ ], │ │
│ │ "env": { │ │
│ │ "DATABASE_URL": │ │
│ │ "postgresql://user:pass@ │ │
│ │ localhost:5432/mydb" │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ ╰────────────────────────────────────────────╯ │
│ │
│ ⚠️ 安全提醒: │
│ - 不要把 .mcp.json 提交到 Git │
│ - 已自动添加到 .gitignore │
│ - 生产环境密码建议使用环境变量 │
│ │
│ ⚙️ Tool: Edit → .gitignore │
│ Added: .mcp.json │
│ │
│ ✅ 配置完成！重启后你可以说: │
│ - "查看用户表的前 10 条记录" │
│ - "这个 SQL 查询有性能问题吗？" │
│ - "最近 7 天新注册了多少用户？" │
│ │
╰──────────────────────────────────────────────────────╯
场景 3：使用已配置的 MCP 工具
> 帮我查一下数据库里过去 7 天的新用户数
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ ⚙️ Tool: postgres_query │
│ $ SELECT COUNT(*) as new_users, │
│ DATE(created_at) as date │
│ FROM users │
│ WHERE created_at > NOW() - INTERVAL '7 days' │
│ GROUP BY DATE(created_at) │
│ ORDER BY date DESC; │
│ │
│ 📊 过去 7 天新用户: │
│ ╭────────────────────────────────╮ │
│ │ 日期 │ 新增用户 │ │
│ │───────────│────────────────│ │
│ │ 03-22 │ 145 ████████████ │ │
│ │ 03-21 │ 128 ██████████ │ │
│ │ 03-20 │ 112 █████████ │ │
│ │ 03-19 │ 98 ████████ │ │
│ │ 03-18 │ 134 ███████████ │ │
│ │ 03-17 │ 156 █████████████│ │
│ │ 03-16 │ 143 ████████████ │ │
│ ╰────────────────────────────────╯ │
│ │
│ 📈 趋势: 日均新增 131 人，周末(03-17)注册量 │
│ 最高(156)，工作日(03-19)最低(98)。 │
│ 整体 7 日总计: 916 位新用户。 │
│ │
╰──────────────────────────────────────────────────────╯
💻 代码演示
# ✅ 使用 claude mcp 命令管理 MCP Server
claude mcp add github \
-e GITHUB_TOKEN=ghp_xxxx \
-- npx -y @anthropic-ai/mcp-server-github
claude mcp add postgres \
--scope project \
-e DATABASE_URL=postgresql://localhost/mydb \
-- npx -y @anthropic-ai/mcp-server-postgres
# ✅ 列出所有已配置的 MCP Server
claude mcp list
# ✅ 移除 MCP Server
claude mcp remove postgres
# ✅ 测试连接是否正常
claude "列出所有可用的 MCP 工具"
# ✅ 安全最佳实践：使用 .env 文件
# .mcp.json 中引用环境变量
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}
排查常见配置问题
# 问题 1: MCP Server 启动失败
# 手动运行 Server 命令查看错误
npx -y @anthropic-ai/mcp-server-github
# 问题 2: Token 过期
# 检查环境变量是否正确设置
echo $GITHUB_TOKEN
# 问题 3: 数据库连接超时
# 确认数据库服务在运行
pg_isready -h localhost -p 5432
# 问题 4: 权限不足
# 检查 Token 是否有所需的 Scope
curl -H "Authorization: Bearer ghp_xxx" \
https://api.github.com/user
🔧 涉及的 Tools / Commands
| 命令/工具 | 用途 | 说明 |
|---|---|---|
claude mcp add |
添加 MCP Server | 支持 --scope project/user |
claude mcp list |
列出已配置 Server | 显示状态和工具数量 |
claude mcp remove |
移除 Server | 从配置中删除 |
settings.json |
全局配置 | ~/.claude/settings.json |
.mcp.json |
项目配置 | 项目根目录 |
📝 本期要点回顾
- MCP 配置分 全局 和 项目级，按安全需求选择
- 使用
claude mcp add命令是最简单的配置方式 - 敏感凭据 不要硬编码，使用环境变量
.mcp.json应加入.gitignore防止泄露- 配置好后用 自然语言 即可调用所有 MCP 工具