Claude Code MCP 配置指南：让 AI 连接任何外部服务

┌─────────────────────────────────────────────────────┐
│              MCP 客户端（宿主）                        │
│     Claude Code / Cursor / VS Code Copilot          │
├─────────────────────────────────────────────────────┤
│              MCP 协议层                              │
│           JSON-RPC 2.0 over STDIO 或 HTTP            │
├─────────────────────────────────────────────────────┤
│              MCP 服务器                              │
│      你的自定义工具、数据源、提示词模板                  │
└─────────────────────────────────────────────────────┘

claude mcp add <名称> <命令> [参数...]

claude mcp add filesystem npx @anthropic/mcp-filesystem /path/to/allowed/directory

claude mcp add github npx @anthropic/mcp-github

export GITHUB_TOKEN="ghp_your_token_here"

claude mcp add github -e GITHUB_TOKEN=ghp_your_token_here npx @anthropic/mcp-github

claude mcp add slack npx @anthropic/mcp-slack

claude mcp add postgres npx @anthropic/mcp-postgres "postgresql://user:pass@localhost:5432/mydb"

claude mcp add filesystem npx @anthropic/mcp-filesystem /Users/you/projects

claude mcp add context7 npx @anthropic/mcp-context7

# 在所有项目中可用（用户作用域）
claude mcp add --scope user github npx @anthropic/mcp-github

# 仅在当前项目中可用（项目作用域——默认）
claude mcp add --scope project postgres npx @anthropic/mcp-postgres "postgresql://..."

claude mcp list

Project servers:
  postgres: npx @anthropic/mcp-postgres postgresql://user:pass@localhost:5432/mydb

User servers:
  github: npx @anthropic/mcp-github
  slack: npx @anthropic/mcp-slack

claude mcp remove <名称>

claude mcp remove postgres

/mcp

claude mcp add github npx @anthropic/[email protected]

mkdir mcp-weather-server
cd mcp-weather-server
npm init -y

npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

{
  "name": "mcp-weather-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "mcp-weather-server": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio.js";
import { z } from "zod";

// 创建 MCP 服务器
const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});

// 定义工具：获取当前天气
server.registerTool(
  "get_weather",
  {
    title: "Get Weather",
    description: "Get the current weather for a city",
    inputSchema: {
      city: z.string().describe("City name, e.g. 'Tokyo' or 'New York'"),
      units: z
        .enum(["celsius", "fahrenheit"])
        .default("celsius")
        .describe("Temperature units"),
    },
  },
  async ({ city, units }) => {
    // 在实际服务器中，你会在这里调用天气 API
    // 本示例返回模拟数据
    const temperature = units === "celsius" ? 22 : 72;
    const unitLabel = units === "celsius" ? "C" : "F";

    // 重要：日志输出必须使用 console.error，绝不要用 console.log
    console.error(`Fetching weather for ${city}...`);

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              city,
              temperature: `${temperature} ${unitLabel}`,
              condition: "Partly cloudy",
              humidity: "65%",
              wind: "12 km/h NW",
            },
            null,
            2
          ),
        },
      ],
    };
  }
);

// 使用 STDIO 传输层启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP server is running");
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

npm run build

chmod +x dist/index.js

claude mcp add weather node /absolute/path/to/mcp-weather-server/dist/index.js

东京现在天气怎么样？

// 定义资源：支持的城市列表
server.resource("supported-cities", "weather://cities", async (uri) => {
  return {
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify([
          "Tokyo",
          "New York",
          "London",
          "Paris",
          "Sydney",
          "Berlin",
          "Singapore",
        ]),
      },
    ],
  };
});

// 定义提示词模板：天气简报
server.prompt(
  "daily-briefing",
  { city: z.string().describe("City for the weather briefing") },
  ({ city }) => ({
    messages: [
      {
        role: "user" as const,
        content: {
          type: "text" as const,
          text: `Generate a morning weather briefing for ${city}. Include:
1. Current conditions
2. High/low temperatures for the day
3. Chance of rain
4. Recommendation for what to wear

Keep it concise and friendly.`,
        },
      },
    ],
  })
);

// 错误 - 这会破坏 JSON-RPC 协议通道
console.log("Processing request...");

// 正确 - 这会输出到 stderr，是安全的
console.error("Processing request...");

MCP_DEBUG=1 node dist/index.js

claude mcp add weather -e MCP_DEBUG=1 node /path/to/dist/index.js

npx @modelcontextprotocol/inspector node dist/index.js

# macOS
ls ~/Library/Logs/Claude\ Code/mcp*.log

# Linux
ls ~/.local/share/claude-code/logs/mcp*.log

{
  "name": "mcp-weather-server",
  "version": "1.0.0",
  "description": "MCP server that provides weather data",
  "type": "module",
  "bin": {
    "mcp-weather-server": "./dist/index.js"
  },
  "files": ["dist"],
  "keywords": ["mcp", "mcp-server", "weather"]
}

npm run build
npm publish

claude mcp add weather npx mcp-weather-server

# 从私有 Git 仓库安装
claude mcp add internal-tools npx github:your-org/internal-mcp-tools

import { McpServer } from "@modelcontextprotocol/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio.js";
import { z } from "zod";
import pg from "pg";

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});

const server = new McpServer({
  name: "db-query-server",
  version: "1.0.0",
});

server.registerTool(
  "query_database",
  {
    title: "Query Database",
    description: "Run a read-only SQL query against the database",
    inputSchema: {
      sql: z.string().describe("SQL query to execute (SELECT only)"),
    },
  },
  async ({ sql }) => {
    // 安全措施：只允许 SELECT 查询
    const normalized = sql.trim().toUpperCase();
    if (!normalized.startsWith("SELECT")) {
      return {
        content: [
          {
            type: "text" as const,
            text: "Error: Only SELECT queries are allowed",
          },
        ],
        isError: true,
      };
    }

    try {
      const result = await pool.query(sql);
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(result.rows, null, 2),
          },
        ],
      };
    } catch (error) {
      console.error("Query failed:", error);
      return {
        content: [
          {
            type: "text" as const,
            text: `Query error: ${(error as Error).message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

// 将 schema 作为资源暴露，让 Claude 理解数据库结构
server.resource("schema", "db://schema", async (uri) => {
  const result = await pool.query(`
    SELECT table_name, column_name, data_type
    FROM information_schema.columns
    WHERE table_schema = 'public'
    ORDER BY table_name, ordinal_position
  `);
  return {
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(result.rows, null, 2),
      },
    ],
  };
});

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

server.registerTool(
  "get_customer",
  {
    title: "Get Customer",
    description: "Look up a customer by ID or email",
    inputSchema: {
      identifier: z
        .string()
        .describe("Customer ID (cust_xxx) or email address"),
    },
  },
  async ({ identifier }) => {
    const isEmail = identifier.includes("@");
    const endpoint = isEmail
      ? `/api/customers?email=${encodeURIComponent(identifier)}`
      : `/api/customers/${identifier}`;

    const response = await fetch(`${process.env.API_BASE_URL}${endpoint}`, {
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
    });

    if (!response.ok) {
      return {
        content: [
          {
            type: "text" as const,
            text: `API error: ${response.status} ${response.statusText}`,
          },
        ],
        isError: true,
      };
    }

    const customer = await response.json();
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(customer, null, 2),
        },
      ],
    };
  }
);

claude mcp add customer-api \
  -e API_BASE_URL=https://api.internal.company.com \
  -e API_TOKEN=your_token_here \
  node /path/to/dist/index.js

const server = new McpServer({
  name: "project-management",
  version: "1.0.0",
});

// 工具 1：列出任务
server.registerTool(
  "list_tasks",
  {
    title: "List Tasks",
    description: "List tasks from the project board, optionally filtered",
    inputSchema: {
      status: z
        .enum(["todo", "in_progress", "done"])
        .optional()
        .describe("Filter by status"),
      assignee: z
        .string()
        .optional()
        .describe("Filter by assignee username"),
    },
  },
  async ({ status, assignee }) => {
    // 实现代码
  }
);

// 工具 2：创建任务
server.registerTool(
  "create_task",
  {
    title: "Create Task",
    description: "Create a new task on the project board",
    inputSchema: {
      title: z.string().describe("Task title"),
      description: z.string().optional().describe("Task description"),
      assignee: z.string().optional().describe("Username to assign to"),
      priority: z
        .enum(["low", "medium", "high", "critical"])
        .default("medium")
        .describe("Task priority"),
    },
  },
  async ({ title, description, assignee, priority }) => {
    // 实现代码
  }
);

// 工具 3：更新任务状态
server.registerTool(
  "update_task_status",
  {
    title: "Update Task Status",
    description: "Change the status of an existing task",
    inputSchema: {
      taskId: z.string().describe("Task ID"),
      status: z
        .enum(["todo", "in_progress", "done"])
        .describe("New status"),
    },
  },
  async ({ taskId, status }) => {
    // 实现代码
  }
);

## MCP Tools

- Use the `query_database` tool to check data before making schema changes
- Always use `get_customer` to verify customer data instead of guessing
- After completing a task, use `send_slack_message` to notify #dev-updates

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__*",
        "command": "echo \"$(date): Tool $CLAUDE_TOOL_NAME called\" >> ~/.claude/mcp-audit.log"
      }
    ]
  }
}

# 添加 MCP 服务器（项目作用域）
claude mcp add <名称> <命令> [参数...]

# 带环境变量添加
claude mcp add <名称> -e KEY=value <命令> [参数...]

# 添加到用户作用域（所有项目可用）
claude mcp add --scope user <名称> <命令> [参数...]

# 列出所有已配置的服务器
claude mcp list

# 移除服务器
claude mcp remove <名称>

# 检查服务器状态（在 Claude Code 内）
/mcp

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio.js";
import { z } from "zod";

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

server.registerTool(
  "my_tool",
  {
    title: "My Tool",
    description: "What this tool does",
    inputSchema: {
      param: z.string().describe("What this parameter is for"),
    },
  },
  async ({ param }) => {
    console.error(`Processing: ${param}`); // 只能用 stderr！
    return {
      content: [{ type: "text" as const, text: `Result: ${param}` }],
    };
  }
);

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

{
  "type": "module",
  "bin": { "my-server": "./dist/index.js" },
  "dependencies": {
    "@modelcontextprotocol/server": "^2.0.0",
    "zod": "^3.23.0"
  }
}