MCP（Model Context Protocol）是 Anthropic 推出的开放协议，让 LLM 能与外部工具和数据源交互。本文记录 MCP 的配置与使用方法。

概念速览

┌─────────┐    MCP协议    ┌────────────┐
│  客户端  │◄────────────►│  MCP Server │──► 文件系统
│ (Claude) │              │ (工具提供者) │──► 数据库
└─────────┘              └────────────┘──► API 服务

• Host：运行 LLM 的应用（如 Claude Desktop、Claude Code）
• Client：Host 内部与 Server 通信的组件
• Server：提供具体能力的外部服务（文件访问、数据库查询等）

---

---

Claude Code 配置

# 添加 MCP server
claude mcp add <name> <command> [args...]

# 示例：添加文件系统 server
claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# 示例：添加 GitHub server（需要设置 GH_TOKEN 环境变量）
claude mcp add github npx -y @modelcontextprotocol/server-github

# 查看已配置的 server
claude mcp list

# 删除 server
claude mcp remove <name>

项目级配置（仅当前项目生效，配置写入 .claude/settings.json）：

claude mcp add --scope project <name> <command> [args...]

用户级配置（所有项目生效）：

claude mcp add --scope user <name> <command> [args...]

---

常用 MCP Server

文件系统

包名	说明
@modelcontextprotocol/server-filesystem	读写指定目录下的文件

claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

Git & GitHub

包名	说明
@modelcontextprotocol/server-git	Git 操作（commit、log、diff、branch 等）
@modelcontextprotocol/server-github	GitHub API（PR、Issue、Repo 管理）

# Git
claude mcp add git npx -y @modelcontextprotocol/server-git --repository /path/to/repo

# GitHub（需要 GH_TOKEN）
claude mcp add github npx -y @modelcontextprotocol/server-github
# 环境变量：GH_TOKEN=ghp_xxxxxxxx

数据库

包名	说明
@modelcontextprotocol/server-sqlite	SQLite 读写
@modelcontextprotocol/server-postgres	PostgreSQL（只读查询）
@benborla29/mcp-server-mysql	MySQL 查询（只读）

# SQLite
claude mcp add sqlite npx -y @modelcontextprotocol/server-sqlite --db-path /path/to/db.sqlite

# PostgreSQL（需要 DATABASE_URL）
claude mcp add postgres npx -y @modelcontextprotocol/server-postgres
# 环境变量：DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

# MySQL（需要 MYSQL 配置）
claude mcp add mysql npx -y @benborla29/mcp-server-mysql
# 环境变量：MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE

Web & 搜索

包名	说明
@modelcontextprotocol/server-puppeteer	浏览器自动化（截图、抓取、执行 JS）
@modelcontextprotocol/server-brave-search	Brave 搜索引擎
@modelcontextprotocol/server-fetch	HTTP 请求抓取网页内容

# Puppeteer
claude mcp add puppeteer npx -y @modelcontextprotocol/server-puppeteer

# Brave Search（需要 BRAVE_API_KEY）
claude mcp add brave-search npx -y @modelcontextprotocol/server-brave-search
# 环境变量：BRAVE_API_KEY=BSExxxxxxxx

# Fetch
claude mcp add fetch npx -y @modelcontextprotocol/server-fetch

记忆 & 思维

包名	说明
@modelcontextprotocol/server-memory	持久化记忆存储（跨会话记住上下文）
@modelcontextprotocol/server-sequential-thinking	顺序思维（复杂推理时辅助拆解步骤）

# Memory
claude mcp add memory npx -y @modelcontextprotocol/server-memory

# Sequential Thinking
claude mcp add thinking npx -y @modelcontextprotocol/server-sequential-thinking

开发工具

包名	说明
@upstash/context7-mcp	查询开源库最新文档和示例代码

# Context7（查文档）
claude mcp add context7 npx -y @upstash/context7-mcp

---

SSE 远程 Server

除本地进程外，MCP 也支持连接远程 Server（HTTP/SSE）：

{
  "mcpServers": {
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer sk-xxxx"
      }
    }
  }
}

Claude Code 中：

claude mcp add --transport sse remote-server https://mcp.example.com/sse

---

自定义 MCP Server

用 TypeScript 快速搭建一个 MCP Server：

# 创建项目
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod

# 入口文件 index.ts

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-server", version: "1.0.0" });

// 注册工具
server.tool(
  "get_weather",                          // 工具名
  "获取指定城市的天气",                     // 描述
  { city: z.string().describe("城市名") }, // 参数 schema
  async ({ city }) => {
    // 实际业务逻辑
    return { content: [{ type: "text", text: `${city}今天晴，25°C` }] };
  }
);

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

# 构建并配置到 Claude Code
npx tsc index.ts --outDir dist --module nodenext --target es2022
claude mcp add my-server node /absolute/path/to/dist/index.js

---

排查问题

# Claude Code 中查看 MCP 连接状态
claude mcp list

# 查看 server 日志（Claude Desktop）
# macOS: ~/Library/Logs/Claude/mcp*.log
# Windows: %APPDATA%\Claude\logs\mcp*.log

# 常见问题：
# 1. command not found → 确认 npx/node 在 PATH 中，用绝对路径
# 2. 权限不足 → 检查文件/目录权限
# 3. 环境变量缺失 → 在 MCP 配置中加 env 字段

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GH_TOKEN": "ghp_xxxxxxxx"
      }
    }
  }
}