14 MCP 协议集成

潮海

8人浏览 · 2026-05-27 08:30:47

潮海 · 2026-05-27 08:30:47 发布

本节目标

理解 MCP 协议的设计理念:标准化的 AI-工具通信协议
掌握三种核心原语:Tools、Resources、Prompts
学会 .mcp.json 的配置方法(本地服务器和远程服务器)
熟练配置常用 MCP Server:GitHub、Playwright、Figma、Postgres、Filesystem
掌握 MCP 安全配置原则:最小权限、目录隔离、用户审批

核心知识点

MCP 协议的核心设计

在 MCP 出现之前,每个 AI 工具都有自己的集成方式:有的是 REST API,有的是 SDK,有的是自定义插件。这意味着每接入一个新工具,都需要写一套新的适配代码。

MCP 协议解决了这个问题。它定义了三个标准化的通信原语:

┌──────────────────────────────────────┐
│            Claude Code               │
│          (MCP Client)                │
└──────┬──────────┬──────────┬─────────┘
       │ Tools    │ Resources│ Prompts
       ▼          ▼          ▼
┌──────────────────────────────────────┐
│          MCP Server                  │
│    (GitHub / Postgres / Figma ...)   │
└──────────────────────────────────────┘

三种核心原语

1. Tools (工具)

Tools 是 MCP 最核心的原语。它让 Claude Code 能够执行操作:

// MCP Server 向 Client 注册的工具描述
{
  "name": "create_issue",
  "description": "在 GitHub 仓库中创建新的 Issue",
  "inputSchema": {
    "type": "object",
    "properties": {
      "owner": { "type": "string", "description": "仓库所有者" },
      "repo": { "type": "string", "description": "仓库名称" },
      "title": { "type": "string", "description": "Issue 标题" },
      "body": { "type": "string", "description": "Issue 内容" }
    },
    "required": ["owner", "repo", "title"]
  }
}

Claude Code 看到这个工具描述后,就知道如何调用它。用户在对话中说"帮我创建一个 Issue",Claude Code 会自动填充参数并调用 create_issue 工具。

2. Resources (资源)

Resources 让 Claude Code 能够读取数据:

// MCP Server 暴露的资源描述
{
  "uri": "postgres://app/users/schema",
  "name": "Users 表结构",
  "description": "app 数据库中 users 表的完整 DDL",
  "mimeType": "text/plain"
}

Resources 与 Tools 的关键区别:

Tools = 执行操作(写)
Resources = 读取数据(读)

3. Prompts (提示词模板)

Prompts 是 MCP Server 提供的预定义提示词模板:

{
  "name": "code_review",
  "description": "标准化代码审查提示词",
  "arguments": [
    { "name": "language", "description": "编程语言", "required": true }
  ]
}

当用户选择使用这个 Prompt 模板时,Server 会返回一段结构化的提示词,Client 将其注入到对话中。

.mcp.json 配置

MCP 配置通过项目根目录的 .mcp.json 文件管理:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-playwright"],
      "env": {
        "PLAYWRIGHT_BROWSERS_PATH": "/usr/local/share/playwright"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/myapp"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-filesystem",
        "/home/user/projects",
        "/home/user/documents"
      ]
    }
  }
}

本地服务器 vs 远程服务器:

{
  "mcpServers": {
    "local-tool": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "description": "本地运行的 MCP 服务器"
    },
    "remote-ai": {
      "url": "https://mcp.example.com/server/sse",
      "headers": {
        "Authorization": "Bearer ${MCP_API_KEY}"
      },
      "description": "远程托管的 MCP 服务器"
    }
  }
}

常用 MCP Server 配置详解

1. GitHub MCP Server

让 Claude Code 能够操作 GitHub:管理 Issues、PR、搜索代码、读写文件。

{
  "github": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

需要生成的 GitHub Token 权限:

repo (私有仓库需要)
read:org (组织信息)
workflow (如果需要操作 Actions)

安装后,Claude Code 可以执行:

"列出当前仓库的所有 open PR"
"在 main 分支上创建一个修复登录 bug 的 PR"
"搜索代码库中所有使用 deprecatedFunction 的地方"

2. Playwright MCP Server

让 Claude Code 能够控制浏览器:自动化测试、网页截图、爬取数据。

{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-playwright"]
  }
}

使用示例:

"打开 https://example.com,截个全页截图"
"填写登录表单,用户名为 test@example.com,然后点击提交按钮"
"检查首页的 h1 标题是否包含正确的文字"

3. Figma MCP Server

让 Claude Code 能够读取和操作 Figma 设计文件:

{
  "figma": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-figma"],
    "env": {
      "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
    }
  }
}

4. Postgres MCP Server

让 Claude Code 能够查询和操作 PostgreSQL 数据库:

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:password@localhost:5432/dbname"
    }
  }
}

安全提示:不要在 .mcp.json 中硬编码数据库密码。使用环境变量 ${DATABASE_URL} 引用。

5. Filesystem MCP Server

让 Claude Code 能够访问指定的文件系统路径:

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@anthropic/mcp-server-filesystem",
      "/home/user/projects",
      "/home/user/documents"
    ]
  }
}

MCP 安全配置原则

原则 1:最小权限

只给 MCP Server 它真正需要的权限:

// 错误:给 GitHub Server 完全的文件系统访问权
{
  "github": {
    "env": {
      "GITHUB_TOKEN": "ghp_fullAdminToken"  // 权限过大的 Token
    }
  }
}

// 正确:使用最小权限的 Token
// Token 只需要 repo scope,不需要 admin、delete_repo 等
{
  "github": {
    "env": {
      "GITHUB_TOKEN": "ghp_readonlyToken"  // 如果只需要读,就用读权限
    }
  }
}

原则 2:目录隔离

Filesystem MCP Server 应该只暴露项目需要访问的目录:

// 危险:暴露整个文件系统
{
  "filesystem": {
    "args": ["-y", "@anthropic/mcp-server-filesystem", "/"]
  }
}

// 安全:只暴露项目目录
{
  "filesystem": {
    "args": ["-y", "@anthropic/mcp-server-filesystem", "/home/user/projects/my-app"]
  }
}

原则 3:用户审批机制

Claude Code v2.1.x 对 MCP 工具调用默认要求用户审批。你可以在 settings.json 中配置:

{
  "permissions": {
    "mcp": {
      "github": {
        "tools": {
          "list_issues": "allow",
          "get_issue": "allow",
          "create_issue": "ask",
          "create_pull_request": "ask",
          "merge_pull_request": "deny"
        }
      },
      "playwright": {
        "tools": {
          "browser_navigate": "allow",
          "browser_snapshot": "allow",
          "browser_click": "ask",
          "browser_fill_form": "ask"
        }
      }
    }
  }
}

权限级别:

allow: 自动允许,无需用户确认
ask: 每次执行前询问用户(默认)
deny: 完全禁止,即使用户同意也无法执行

实操步骤

步骤 1:安装第一个 MCP Server

在本项目中安装 GitHub MCP Server:

# 1. 生成 GitHub Personal Access Token
# 访问 https://github.com/settings/tokens
# 权限勾选: repo, read:org

# 2. 添加到环境变量
export GITHUB_TOKEN="ghp_your_token_here"

# 3. 在项目根目录创建 .mcp.json
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
EOF

步骤 2:验证 MCP Server 是否正常

在 Claude Code 中测试:

# 测试 GitHub MCP Server
"列出当前仓库最近 5 个 issue"
"搜索代码库中所有包含 TODO 注释的文件"

如果正常返回结果,说明 MCP Server 已正确配置。

步骤 3:配置多 MCP Server

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-playwright"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-filesystem",
        "/home/user/projects/my-app"
      ]
    }
  }
}

步骤 4:配置权限策略

// ~/.claude/settings.json
{
  "permissions": {
    "mcp": {
      "github": {
        "tools": {
          "create_pull_request": "ask",
          "merge_pull_request": "deny",
          "push_files": "deny"
        }
      },
      "filesystem": {
        "tools": {
          "read_file": "allow",
          "write_file": "ask",
          "delete_file": "deny"
        }
      }
    }
  }
}

避坑指南

坑 1:环境变量未正确传递

.mcp.json 中使用的 ${VARIABLE} 语法需要环境变量在 Claude Code 启动时已经设置:

# 正确:先设置再启动
export GITHUB_TOKEN="ghp_xxx"
claude

# 或者放在 ~/.bashrc / ~/.zshrc 中
# 或者使用 .env 文件配合 direnv

不确定环境变量是否生效时,在 Claude Code 中测试:

"请尝试获取当前仓库信息,验证 GitHub 连接是否正常"

坑 2:MCP Server 版本不兼容

MCP 协议仍在快速演进中。使用 npx -y 可以确保每次都用最新版本,但也可能引入不兼容的变更:

// 建议:固定版本号
{
  "github": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-github@0.2.0"]
  }
}

坑 3:多个 MCP Server 的工具名冲突

两个 MCP Server 可能注册了同名工具。Claude Code 会用命名空间区分:

# Tool 调用时的完整名称
mcp__github__list_issues
mcp__jira__list_issues

在配置文件中也使用完整名称配置权限。

坑 4:忽略了 MCP Server 的资源消耗

每个 MCP Server 都是一个独立的进程:

Playwright 会启动一个完整的浏览器实例(占用大量内存)
Postgres 会维持数据库连接池
Filesystem 会监控文件变化

同时启动过多 MCP Server 可能导致 4-8GB 的内存消耗。建议按需开启,不要在 .mcp.json 中堆砌所有可能的 Server。

课后作业

作业 1:安装并配置 GitHub MCP Server

在你的项目中配置 GitHub MCP Server
让 Claude Code 执行以下操作:
- 搜索代码库中使用了某个过时函数的文件
- 列出本周创建的 Issues
- 查看最近合并的 PR 的变更内容
记录哪些操作最实用,哪些权限需要调整

作业 2:配置 Playwright MCP Server

安装 Playwright MCP Server
编写一个自动化流程:
- 打开你的项目首页
- 截图保存
- 验证关键元素是否存在
- 模拟一个完整的用户交互流程

作业 3:设计团队的 MCP 安全策略

基于你的项目特点,设计一份 .mcp.json 安全模板:

列出项目需要的 MCP Server
为每个 Server 设定最小权限
标记哪些操作需要用户审批,哪些可以自动执行
添加到团队文档中,作为新成员配置 MCP 的标准参考

总结

MCP 协议让 Claude Code 从"只能操作文本和文件的 AI"变成了"能操作整个数字世界的 AI"。但能力的边界应该由你来设定:

Tools (操作) 给了你效率,但要配合权限策略("能创建 Issue,但不能删除仓库")
Resources (数据) 给了你信息,但要控制暴露范围("能读项目文件,但不能读系统文件")
Prompts (模板) 给了你一致性,但要审查模板质量("用团队统一的审查模板,而不是我随便写的一段话")

MCP 配置的原则很简单:每次只给 Claude Code 刚好够用的权限,不多一分,不少一分。当你对一个 MCP Server 的安全边界不确定时,默认用 deny 或 ask,等确认安全后再放开为 allow。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

RAG技术怎么让AI笔记工具读懂你的知识库？

AtomGit开源社区

从 NVIDIA 驱动到 CUDA + cuDNN 完全配置指南（附避坑）

恭喜你！走到这一步，你的电脑已经是一台名副其实的深度学习工作站了。用 GPU 加速训练神经网络（速度提升几十到上百倍）跑 LLM（大语言模型）、Stable Diffusion（AI 绘画）等前沿项目课后作业运行一个 MNIST 手写数字识别的 PyTorch 示例，观察 GPU 使用率（在任务管理器性能选项卡查看）。尝试用nvidia-smi实时监控显存占用。有任何问题请在评论区留言，我会尽量解