MCP 配置与使用指南

前置要求

• Node.js 18+ 或 Python 3.10+
• Claude Desktop 或支持 MCP 的编辑器（Cursor、VS Code + Cline）
• 基本的命令行操作能力

一、Claude Desktop 配置

1. 找到配置文件

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 基础配置结构

{
  "mcpServers": {
    "服务器名称": {
      "command": "启动命令",
      "args": ["参数列表"],
      "env": {
        "环境变量": "值"
      }
    }
  }
}

3. 配置文件系统访问

这是最常用的 MCP 服务器，让 Claude 可以读写本地文件：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents",
        "/Users/你的用户名/Desktop"
      ]
    }
  }
}

说明：

• args 中的路径是允许 Claude 访问的目录
• 可以添加多个路径
• 出于安全考虑，只开放必要的目录

4. 配置 GitHub 集成

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

获取 GitHub Token：

1. 访问 GitHub → Settings → Developer settings → Personal access tokens
2. 创建 token，勾选 repo 权限

5. 配置数据库（PostgreSQL）

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

6. 完整配置示例

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/Projects",
        "/Users/me/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

7. 重启 Claude Desktop

配置保存后，完全退出并重启 Claude Desktop。

验证方法：在对话中问 Claude "你能访问哪些 MCP 工具？"

二、Cursor 配置

1. 找到配置文件

Cursor 的 MCP 配置位于项目根目录：

.cursor/mcp.json

或全局配置：

• macOS: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

2. 配置示例

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-context7"]
    }
  }
}

3. 启用 MCP

在 Cursor 设置中：

1. 打开 Settings (Cmd/Ctrl + ,)
2. 搜索 "MCP"
3. 确保 MCP 功能已启用

三、Claude Code 配置

1. 项目级配置

在项目根目录创建 .claude/mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    }
  }
}

2. 使用 MCP 工具

在 Claude Code 会话中，直接描述需求：

> 读取 package.json 并分析依赖
> 帮我查询数据库中的用户表结构
> 在 GitHub 上创建一个新 Issue

四、常用 MCP 服务器安装

文件系统

npx @modelcontextprotocol/server-filesystem /path/to/dir

GitHub

GITHUB_PERSONAL_ACCESS_TOKEN=xxx npx @modelcontextprotocol/server-github

PostgreSQL

POSTGRES_CONNECTION_STRING=xxx npx @modelcontextprotocol/server-postgres

SQLite

npx mcp-server-sqlite-npx --db-path /path/to/database.db

Puppeteer（浏览器控制）

npx @modelcontextprotocol/server-puppeteer

Memory（持久记忆）

npx @modelcontextprotocol/server-memory

Brave Search（网络搜索）

BRAVE_API_KEY=xxx npx @modelcontextprotocol/server-brave-search

五、开发自定义 MCP 服务器

TypeScript 示例

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 定义工具
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "hello",
      description: "Say hello to someone",
      inputSchema: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name to greet" }
        },
        required: ["name"]
      }
    }
  ]
}));

// 实现工具
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "hello") {
    const name = request.params.arguments.name;
    return { content: [{ type: "text", text: `Hello, ${name}!` }] };
  }
});

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

Python 示例

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-server")

@server.tool()
async def hello(name: str) -> str:
    """Say hello to someone"""
    return f"Hello, {name}!"

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            server.create_initialization_options()
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

六、常见问题

Q: MCP 服务器无法启动

检查步骤：

1. 确认 Node.js 版本 >= 18
2. 检查配置文件 JSON 格式是否正确
3. 查看命令行输出的错误信息

Q: Claude 看不到 MCP 工具

解决方法：

1. 完全退出 Claude Desktop（不是最小化）
2. 检查配置文件路径是否正确
3. 验证 JSON 格式无误

Q: 文件系统访问被拒绝

原因：路径不在配置的允许列表中

解决：在 args 中添加需要访问的目录路径

Q: GitHub Token 无效

检查：

1. Token 是否过期
2. Token 权限是否足够
3. 环境变量名是否正确

七、安全最佳实践

1. 最小权限原则：只开放必要的目录和权限
2. 敏感信息：不要在配置文件中硬编码密码
3. 定期审查：检查哪些 MCP 服务器在运行
4. 更新维护：及时更新 MCP 服务器版本
5. 日志监控：关注 MCP 服务器的操作日志

八、推荐配置组合

开发者基础套装

{
  "mcpServers": {
    "filesystem": { ... },
    "github": { ... },
    "memory": { ... }
  }
}

数据分析套装

{
  "mcpServers": {
    "filesystem": { ... },
    "postgres": { ... },
    "puppeteer": { ... }
  }
}

全能套装

{
  "mcpServers": {
    "filesystem": { ... },
    "github": { ... },
    "postgres": { ... },
    "memory": { ... },
    "puppeteer": { ... },
    "brave-search": { ... }
  }
}