MCP 服务器配置

完整的 Model Context Protocol (MCP) 服务器配置指南，让 Claude Code 具备更强大的外部系统集成能力。

MCP 概述

什么是 MCP？

Model Context Protocol (MCP) 是一个开放标准，允许 Claude Code 与外部工具和服务进行安全通信。通过 MCP 服务器，Claude Code 可以：

实时数据访问：搜索引擎、数据库、API
文件系统操作：读写文件、目录管理
代码仓库集成：GitHub、GitLab 等平台
开发工具集成：数据库、监控系统等

MCP 架构

Claude Code ← MCP Protocol → MCP Server ← API/Tool → External Service

基础配置

1. 配置文件位置

MCP 服务器在 Claude Code 配置文件中定义：

# 全局配置
~/.claude/config.json
 
# 项目配置 (可选)
./.claude/mcp.json

2. 基本配置结构

{
  "mcpServers": {
    "server-name": {
      "command": "executable-path",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

官方 MCP 服务器

1. Brave 搜索服务器

实时网页搜索能力：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["@brave/search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

安装步骤：

# 获取 Brave Search API Key
# 访问 https://api.search.brave.com
 
# 测试连接
claude mcp test brave-search
 
# 使用示例
搜索 "Next.js 15 最新特性"

2. GitHub 集成服务器

代码仓库操作能力：

{
  "mcpServers": {
    "github": {
      "command": "npx", 
      "args": ["@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

功能特性：

仓库搜索和浏览
Issue 和 PR 管理
代码审查集成
发布管理

3. 文件系统服务器

本地文件操作：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-filesystem", "/allowed/path"],
      "env": {}
    }
  }
}

⚠️

⚠️ 安全提示：文件系统服务器需要明确指定允许访问的路径，避免权限过大。

4. SQLite 数据库服务器

数据库查询能力：

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-sqlite", "/path/to/database.db"],
      "env": {}
    }
  }
}

第三方 MCP 服务器

社区维护的服务器

Redis 服务器：

{
  "mcpServers": {
    "redis": {
      "command": "npx",
      "args": ["@community/mcp-redis-server"],
      "env": {
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

Docker 服务器：

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["@community/mcp-docker-server"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Slack 集成：

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["@community/mcp-slack-server"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_APP_TOKEN": "xapp-your-token"
      }
    }
  }
}

自定义 MCP 服务器

1. 创建简单服务器

// my-mcp-server.ts
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio';
import { Server } from '@modelcontextprotocol/sdk/server';
 
const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
});
 
// 注册工具
server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: "get_weather",
      description: "获取天气信息",
      inputSchema: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "城市名称"
          }
        },
        required: ["city"]
      }
    }
  ]
}));
 
// 处理工具调用
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === 'get_weather') {
    // 实现天气查询逻辑
    const weather = await getWeatherData(args.city);
    return {
      content: [{
        type: "text",
        text: `${args.city}的天气：${weather}`
      }]
    };
  }
});
 
// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}
 
main().catch(console.error);

2. 配置自定义服务器

{
  "mcpServers": {
    "my-weather": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "WEATHER_API_KEY": "your-api-key"
      }
    }
  }
}

服务器管理

1. 服务器状态管理

# 查看所有 MCP 服务器
claude mcp list
 
# 检查服务器状态
claude mcp status [server-name]
 
# 启动服务器
claude mcp start [server-name]
 
# 停止服务器
claude mcp stop [server-name]
 
# 重启服务器
claude mcp restart [server-name]

2. 调试和日志

# 启用调试模式
claude --debug mcp test brave-search
 
# 查看服务器日志
claude mcp logs [server-name]
 
# 实时日志监控
claude mcp logs [server-name] --follow

3. 服务器测试

# 测试单个服务器
claude mcp test brave-search
 
# 测试所有服务器
claude mcp test --all
 
# 交互式测试
claude mcp test --interactive github

高级配置

1. 服务器优先级

{
  "mcpServers": {
    "primary-search": {
      "command": "npx",
      "args": ["@brave/search-mcp-server"],
      "priority": 1,
      "env": {
        "BRAVE_API_KEY": "key"
      }
    },
    "fallback-search": {
      "command": "npx", 
      "args": ["@duckduckgo/mcp-server"],
      "priority": 2,
      "env": {}
    }
  }
}

2. 条件启用

{
  "mcpServers": {
    "development-db": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-sqlite", "./dev.db"],
      "enabled": "${NODE_ENV === 'development'}",
      "env": {}
    }
  }
}

3. 资源限制

{
  "mcpServers": {
    "memory-intensive": {
      "command": "npx",
      "args": ["@community/mcp-ai-server"],
      "limits": {
        "memory": "512MB",
        "timeout": 30000,
        "maxRequests": 100
      },
      "env": {}
    }
  }
}

安全配置

1. 权限控制

{
  "mcpServers": {
    "restricted-fs": {
      "command": "npx",
      "args": ["@anthropic/mcp-server-filesystem"],
      "permissions": {
        "read": ["/home/user/projects"],
        "write": ["/home/user/projects/output"],
        "execute": false
      }
    }
  }
}

2. 网络安全

{
  "mcpServers": {
    "web-api": {
      "command": "npx",
      "args": ["@community/mcp-web-server"],
      "security": {
        "allowedDomains": ["api.example.com"],
        "requireTLS": true,
        "validateCertificates": true
      }
    }
  }
}

3. 敏感信息管理

# 使用环境变量文件
echo "GITHUB_TOKEN=your_token" > .env.mcp
 
# 配置中引用
{
  "mcpServers": {
    "github": {
      "envFile": ".env.mcp",
      "command": "npx",
      "args": ["@github/mcp-server"]
    }
  }
}

故障排查

常见问题

服务器无法启动：

# 检查命令路径
which npx
npm ls -g @brave/search-mcp-server
 
# 检查权限
ls -la ~/.claude/config.json
 
# 手动启动测试
npx @brave/search-mcp-server

API Key 错误：

# 验证环境变量
echo $BRAVE_API_KEY
 
# 测试 API 连接  
curl -H "X-Subscription-Token: $BRAVE_API_KEY" \
  "https://api.search.brave.com/res/v1/web/search?q=test"

连接超时：

{
  "mcpServers": {
    "slow-server": {
      "timeout": 60000,
      "retries": 3,
      "backoff": "exponential"
    }
  }
}

诊断工具

# MCP 系统诊断
claude mcp diagnose
 
# 服务器健康检查
claude mcp health-check --all
 
# 配置验证
claude mcp validate-config

最佳实践

1. 服务器选择

官方优先：优先使用官方维护的服务器
社区验证：使用经过社区验证的第三方服务器
安全审查：自定义服务器需要安全审查

2. 性能优化

按需启动：只启动必要的服务器
资源限制：设置合理的内存和超时限制
缓存策略：启用适当的缓存机制

3. 监控运维

日志记录：启用详细的日志记录
监控指标：监控服务器响应时间和成功率
定期更新：保持服务器版本更新