AI导哈

模型上下文协议管理工具

用于在Claude Code CLI和Claude Desktop中添加和管理MCP（Model Context Protocol）服务器的工具，支持多种传输类型和配置选项。

  • by justinwlin
  • 混合部署
  • 5 星标
  • 更新于
在 GitHub 查看 justinwlin/claude-mcp-guide

使用说明

克劳德MCP指南

在中添加和管理MCP（模型上下文协议）服务器的参考指南 Claude 代码命令行界面 和 克劳德桌面版.

目录

什么是MCP？

这 模型上下文协议 是一个开放标准，允许AI助手连接到外部工具和数据源。MCP服务器公开了Claude可以调用的“工具”，比如读取数据库、调用API、管理文件等。

MCP服务器通过以下三种传输方式之一进行通信：

  • 标准 --Claude将服务器创建为子进程，并通过stdin/stdout进行通信（最常见于本地服务器）
  • 上海证券交易所 --服务器通过HTTP发送事件
  • 超文本传输协议 --可流式HTTP传输

Claude 代码命令行界面

添加服务器

claude mcp add <server-name> [options] -- <command> [args...]

这 -- 将Claude的选项与服务器命令分开。一切之后 -- 是用于启动MCP服务器的命令。

运输类型

# stdio (default) — runs a local process
claude mcp add my-server -- node /path/to/server.js

# HTTP/SSE — connects to a remote URL
claude mcp add my-server --transport http https://example.com/mcp

# SSE (legacy)
claude mcp add my-server --transport sse https://example.com/sse

作用域选项

标志 范围 配置文件 描述
-s user 用户（全局） ~/.claude.json 适用于所有项目
-s project 项目 .mcp.json （项目根目录） 仅在此项目中可用，可以通过git共享 
# Global — available everywhere
claude mcp add my-server -s user -- node server.js

# Project-only — lives in .mcp.json, can be committed
claude mcp add my-server -s project -- node server.js

环境变量

传递环境变量 -e:

claude mcp add my-server \
  -e API_KEY=sk-abc123 \
  -e DATABASE_URL=postgres://localhost/db \
  -- node server.js

管理服务器

# List all configured servers and their health
claude mcp list

# Remove a server
claude mcp remove <server-name> -s user    # remove from user scope
claude mcp remove <server-name> -s project # remove from project scope

# Reconnect servers (in an active session)
/mcp

克劳德桌面版

配置文件位置

操作系统 路径
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
窗户 %APPDATA%\Claude\claude_desktop_config.json

配置格式

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server.js", "--flag"],
      "env": {
        "API_KEY": "your-key",
        "OTHER_VAR": "value"
      }
    }
  }
}

编辑后，重新启动Claude Desktop以获取更改。

常见模式

npm包（npx）

对于npm上已发布的MCP服务器：

# Claude Code CLI
claude mcp add my-server -- npx -y some-mcp-package

# Claude Desktop
{
  "command": "npx",
  "args": ["-y", "some-mcp-package"]
}

这 -y flag auto确认npx安装提示。

本地Node.js服务器

对于您在本地克隆和构建的服务器：

# Claude Code CLI
claude mcp add my-server -- node /path/to/build/index.js

# Claude Desktop
{
  "command": "node",
  "args": ["/path/to/build/index.js"]
}

Python服务器

# Claude Code CLI
claude mcp add my-server -- python /path/to/server.py

# Using uvx (Python package runner, like npx for Python)
claude mcp add my-server -- uvx some-mcp-package

# Claude Desktop
{
  "command": "python",
  "args": ["/path/to/server.py"]
}

Docker容器

# Claude Code CLI
claude mcp add my-server -- docker run -i --rm \
  -e API_KEY=value \
  some-image:latest

# Claude Desktop
{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "API_KEY=value",
    "some-image:latest"
  ]
}

-i （交互式）是stdio传输所必需的，因此Docker保持stdin打开。 --rm 在容器离开后将其清理干净。

远程HTTP/SSE服务器

# Claude Code CLI
claude mcp add my-server --transport http https://example.com/mcp

# With auth header
claude mcp add my-server --transport http https://example.com/mcp \
  --header "Authorization:Bearer your-token"

对于Claude Desktop，请使用 mcp-remote 桥接远程服务器：

{
  "command": "npx",
  "args": [
    "mcp-remote",
    "https://example.com/sse",
    "--header",
    "Authorization:${AUTH_HEADER}"
  ],
  "env": {
    "AUTH_HEADER": "Bearer your-token"
  }
}

真实世界的例子

实际预算MCP

个人理财工具集成：

# Claude Code CLI
claude mcp add actual-budget \
  -s user \
  -e ACTUAL_SERVER_URL=https://your-actual-server.com \
  -e ACTUAL_PASSWORD=your-password \
  -e ACTUAL_BUDGET_SYNC_ID=your-budget-id \
  -e DOTENV_CONFIG_QUIET=true \
  -- node /path/to/actual-mcp/build/index.js --enable-write

// Claude Desktop
{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/path/to/actual-mcp/build/index.js", "--enable-write"],
      "env": {
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id",
        "DOTENV_CONFIG_QUIET": "true"
      }
    }
  }
}

DOTENV_CONFIG_QUIET=true 因为dotenv v17+会打印到stdout，这会损坏stdio MCP传输。

--enable-write 启用写入工具（创建/更新/删除事务、类别等）。

线性MCP

项目管理集成（远程HTTP）：

# Claude Code CLI
claude mcp add linear --transport http https://mcp.linear.app/mcp

Linear在您首次连接时通过浏览器中的OAuth处理身份验证。

剧作家MCP

浏览器自动化：

# Claude Code CLI
claude mcp add playwright -- npx @anthropic-ai/mcp-server-playwright@latest

// Claude Desktop
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-playwright@latest"]
    }
  }
}

MCP概念

Notion工作区集成（远程HTTP）：

# Claude Code CLI
claude mcp add notion --transport http https://mcp.notion.com/mcp

文件系统MCP

让Claude访问特定目录：

# Claude Code CLI
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

// Claude Desktop
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents",
        "/Users/you/Projects"
      ]
    }
  }
}

故障排除

“意外令牌”/“无效JSON”

服务器正在将非JSON输出打印到stdout，破坏了stdio传输。常见原因：

  • Dotenv V17+ 将日志行打印到stdout。修复：设置 DOTENV_CONFIG_QUIET=true 在env变量中。
  • console.log（） 在服务器代码中。MCP服务器只能将协议消息写入stdout。使用 console.error() 用于日志记录。

“服务器已断开连接”

  • 检查服务器是否可以独立运行： node /path/to/server.js --test-resources （如果支持）
  • 验证环境变量是否正确
  • 检查版本是否不匹配（例如，API库比其连接的服务器旧）

“不同步迁移”

具体到实际预算：您的 @actual-app/api npm包版本比您的实际预算服务器旧。升级软件包：

npm install @actual-app/api@latest
npm run build

服务器显示“已连接”，但未显示任何工具

  • 重新启动克劳德代码会话或克劳德桌面
  • 一些服务器需要标志来启用工具（例如。， --enable-write 实际mcp）
  • 检查 claude mcp list 验证连接状态

权限错误

  • 确保服务器二进制文件/脚本可执行
  • 对于Docker，确保Docker桌面正在运行
  • 对于npx，确保npm/node在你的PATH上

提示

  • 使用 claude mcp list 定期检查服务器健康状况。
  • 使用 -s project 并承诺 .mcp.json 与您的团队共享MCP配置（但要在环境变量或单独的环境变量中保密） .env).
  • 使用 DOTENV_CONFIG_QUIET=true 任何时候服务器使用dotenv v17+。
  • 首先在本地测试服务器 在将它们添加到克劳德之前。直接运行server命令并检查stderr上的错误。
  • 保持MCP服务器包的更新 以避免与它们连接的服务版本不匹配。
  • 使用 /mcp 克劳德代码 在不重新启动会话的情况下重新连接服务器。

最后更新日期：2026年2月

相关 MCP