{
  "id": "art_nwr2OnGQIlfg",
  "slug": "how-to-configure-mcp-servers-in-claude-code",
  "author": "句芒（goumang）",
  "title": "如何在 Claude Code 中配置 MCP Server？",
  "summary": "详细讲解在 Claude Code 中配置 MCP Server 的完整流程，包括配置文件位置、标准结构、路径规范、常见错误排查。适用于需要为 Claude Code 添加工具能力的开发者。",
  "content": "# 如何在 Claude Code 中配置 MCP Server？\n\n本文详细讲解在 Claude Code 中配置 MCP Server 的完整流程，帮助你为 Claude Code 添加文件系统、数据库、GitHub 等工具能力。\n\n## 配置文件位置\n\nClaude Code 使用 `claude_desktop_config.json` 文件配置 MCP Servers，文件位置根据操作系统不同：\n\n### macOS\n```\n~/Library/Application Support/Claude/claude_desktop_config.json\n```\n\n### Windows\n```\n%APPDATA%/Claude/claude_desktop_config.json\n```\n\n### Linux\n```\n~/.config/Claude/claude_desktop_config.json\n```\n\n## 标准配置结构\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/Documents\",\n        \"/Users/username/Downloads\"\n      ]\n    },\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-postgres\",\n        \"postgresql://localhost/mydb\"\n      ]\n    },\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-github\"\n      ],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n## 配置字段说明\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `command` | string | 是 | 启动命令，如 `npx`, `uvx`, `node` |\n| `args` | array | 是 | 命令参数数组 |\n| `env` | object | 否 | 环境变量，如 API Token |\n\n## 常用 MCP Server 配置示例\n\n### 文件系统 (filesystem)\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/path/to/allowed/directory\"\n      ]\n    }\n  }\n}\n```\n\n### PostgreSQL 数据库\n```json\n{\n  \"mcpServers\": {\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-postgres\",\n        \"postgresql://user:password@localhost:5432/dbname\"\n      ]\n    }\n  }\n}\n```\n\n### GitHub\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-github\"\n      ],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_xxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n## 配置步骤\n\n1. **创建/编辑配置文件**\n   ```bash\n   # macOS 示例\n   mkdir -p ~/Library/Application\\ Support/Claude\n   touch ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n   ```\n\n2. **添加 MCP Server 配置**\n   参考上面的配置示例，添加你需要的工具\n\n3. **验证 JSON 格式**\n   ```bash\n   # 使用 jq 验证\n   cat ~/Library/Application\\ Support/Claude/claude_desktop_config.json | jq\n   ```\n\n4. **重启 Claude Code**\n   完全退出 Claude Code（不只是关闭窗口），然后重新启动\n\n5. **验证工具加载**\n   在 Claude Code 中输入 `/mcp` 查看已加载的工具\n\n## 常见错误排查\n\n### JSON 格式错误\n- 症状：Claude Code 启动时报错\n- 解决：使用 `jq` 或 JSON 验证器检查格式\n\n### 路径错误\n- 症状：工具无法访问指定目录\n- 解决：检查路径是否存在，使用绝对路径\n\n### 权限不足\n- 症状：文件操作被拒绝\n- 解决：检查文件系统权限，或调整 allowedDirectories\n\n### 命令未找到\n- 症状：`npx: command not found`\n- 解决：确保 Node.js 已安装并添加到 PATH\n\n## 下一步\n\n- 📖 [MCP Server 启动失败排查](TRANS-001)\n- 🔧 [文件系统工具配置详解](TOOL-FS-001)\n- 📁 [PostgreSQL 工具配置详解](TOOL-PG-001)",
  "lang": "zh",
  "domain": "agent",
  "tags": [
    "mcp",
    "claude-code",
    "configuration",
    "setup",
    "指南"
  ],
  "keywords": [
    "mcp",
    "claude-code",
    "configuration",
    "claude_desktop_config.json",
    "setup",
    "filesystem",
    "postgres",
    "github"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 0,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "配置文件在哪里？",
      "answer": "macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %APPDATA%/Claude/claude_desktop_config.json；Linux: ~/.config/Claude/claude_desktop_config.json"
    },
    {
      "id": "qa_002",
      "question": "如何验证配置是否正确？",
      "answer": "1. 使用 jq 验证 JSON 格式；2. 重启 Claude Code；3. 输入 /mcp 查看已加载的工具"
    },
    {
      "id": "qa_003",
      "question": "修改配置后需要重启吗？",
      "answer": "是的，必须完全退出 Claude Code（不只是关闭窗口），然后重新启动才能加载新配置。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmn15fyn0006bmwo8rloil4r",
      "articleId": "art_nwr2OnGQIlfg",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T05:31:17.136Z"
    },
    {
      "id": "cmmn15b2h0004bmwo31dt25by",
      "articleId": "art_nwr2OnGQIlfg",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T05:31:10.793Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T03:56:52.454Z",
  "updatedAt": "2026-03-21T18:59:11.143Z",
  "createdAt": "2026-03-12T03:56:52.009Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=how-to-configure-mcp-servers-in-claude-code",
      "json": "/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=json&lang=zh",
      "markdown": "/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=json&lang=zh\""
  }
}