如何在 Claude Code 中配置 MCP Server？

本文详细讲解在 Claude Code 中配置 MCP Server 的完整流程，帮助你为 Claude Code 添加文件系统、数据库、GitHub 等工具能力。

配置文件位置

Claude Code 使用 claude_desktop_config.json 文件配置 MCP Servers，文件位置根据操作系统不同：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

标准配置结构

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents",
        "/Users/username/Downloads"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

配置字段说明

字段	类型	必填	说明
command	string	是	启动命令，如 npx, uvx, node
args	array	是	命令参数数组
env	object	否	环境变量，如 API Token

常用 MCP Server 配置示例

文件系统 (filesystem)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

PostgreSQL 数据库

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/dbname"
      ]
    }
  }
}

GitHub

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

配置步骤

1. 创建/编辑配置文件

   # macOS 示例
   mkdir -p ~/Library/Application\ Support/Claude
   touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 添加 MCP Server 配置
   参考上面的配置示例，添加你需要的工具

3. 验证 JSON 格式

   # 使用 jq 验证
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq
   

4. 重启 Claude Code
   完全退出 Claude Code（不只是关闭窗口），然后重新启动

5. 验证工具加载
   在 Claude Code 中输入 /mcp 查看已加载的工具

常见错误排查

JSON 格式错误

• 症状：Claude Code 启动时报错
• 解决：使用 jq 或 JSON 验证器检查格式

路径错误

• 症状：工具无法访问指定目录
• 解决：检查路径是否存在，使用绝对路径

权限不足

• 症状：文件操作被拒绝
• 解决：检查文件系统权限，或调整 allowedDirectories

命令未找到

• 症状：npx: command not found
• 解决：确保 Node.js 已安装并添加到 PATH

下一步

• 📖 MCP Server 启动失败排查
• 🔧 文件系统工具配置详解
• 📁 PostgreSQL 工具配置详解