MCP server 2026 教程:安装、配置、运行

MCP 到底是什么

Model Context Protocol 是 Anthropic 于 2024 年 11 月发布的一项规范。它定义了一种标准方式 —— 让语言模型调用外部工具,也让外部工具向模型暴露自身能力。在 MCP 出现之前,每一项 AI 工具集成都是定制的;MCP 让集成可组合。

它的架构比名字朴素得多。一个 MCP server 就是在你机器上运行的一个进程(远端托管的 server 也支持)。Claude Code 启动时会拉起每个已配置的 MCP server,接收该 server 提供的工具列表,随后在会话中按名调用这些工具。所有通信走 stdin/stdout,基于 JSON-RPC 2.0。本地 server 不需要 HTTP、不需要端口、也无需任何网络配置。

更系统的概念解读见 MCP 是什么 入门篇。本文聚焦在落地配置上。

配置文件放在哪里

MCP server 配置存放在一个 settings.json 文件中。位置有两个:

• ~/.claude/settings.json —— 全局配置;对本机上所有 Claude Code 会话生效
• .claude/settings.json(项目目录内)—— 项目级配置;仅在 Claude Code 在该目录内运行时生效,并对同名键覆盖全局配置

项目级文件适合放项目专属的 server(例如绑定某个项目数据库连接串的 server)。全局文件适合放你希望在每个项目都能用到的 server(例如 Fetch 与 GitHub)。

基础配置结构

settings.json 中的 mcpServers 键是一个映射:从 server 名称到 server 配置。每条配置说明该 server 进程如何启动。

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

关于这套结构,有几点值得说明:

• npx 上的 -y 参数会在缺包时自动安装。配置阶段很方便,但首次启动会稍慢。可以通过固定版本规避:@modelcontextprotocol/server-filesystem@0.6.0。
• 凭据放在 env 对象中,不要作为命令行参数。参数会被记录;环境变量默认不会。
• Server 名(键)随你定 —— 仅用于错误信息和 Claude 看到的工具描述。

值得优先安装的五个 server

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "github_pat_..."
    }
  }
}

{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"]
  }
}

{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"]
  }
}

验证 server 是否跑起来

修改完 settings.json 后,启动一个新的 Claude Code 会话。在提示符里直接问 Claude 它能用哪些工具:

What MCP tools do you have access to?

Claude 应该会列出你配置过的 server 与各自提供的工具。如果某个 server 缺席,故障通常是这三种之一:

1. 包没装上。npx 上的 -y 会自动装,但首次运行可能因 npm 镜像缓慢或网络防火墙而失败。在终端里手动跑一遍 npx 命令,看具体报错。
2. 路径不对。Filesystem server 接收的是绝对路径。相对路径或拼写错误的路径会导致启动失败。Claude Code 把 MCP server 错误日志记在 ~/.claude/logs/ —— 先去那里查。
3. 凭据无效。如果 server 起来了、但调用工具时报错,最常见的原因是 API key 过期或配置不当。先在 curl 或厂商 API playground 中直接验证凭据,再去排查 MCP 这一层。

项目级 vs 全局配置

Septim 内部的常见做法:全局配置放 Fetch、Memory、Playwright —— 这些在任何项目里都用得上。项目级配置放 Filesystem(允许根设为项目根)、该项目的数据库 server,以及范围限定到本项目仓库的 GitHub server。

这种组织方式让你切到任意项目目录,Claude Code 都会自动加载正确的 server 集合,无需手动切换配置。同名 server 上,项目级文件覆盖全局文件,因此你可以为不同项目配不同的数据库连接,互不冲突。

远端 MCP server

Anthropic 在 2026 年初新增了对远端 MCP server 的支持(走 SSE 而非 stdio)。配置使用 url 键替代 command 与 args:

{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

对于自身维护托管 MCP 端点的服务(Stripe 等已有此能力),远端 server 很方便。代价是每次工具调用多一次网络往返,凭据走线上 —— 务必只用 HTTPS 远端,把 Authorization header 像保护环境变量中的 API key 一样对待。

添加更多 server 之前要做的安全考量

每多装一个 server,就给你的 Claude Code 会话多一份攻击面。MCP server 漏洞清单提供 24 项评估框架。教程层面的简版:

• 只装活跃组织维护或有公司背书的 server
• 安装前阅读源码中的工具描述 —— 嵌在工具元数据里的恶意指令是已记录在案的攻击向量(arXiv 2603.22489)
• 使用最小权限凭据 —— 只读单仓库的 GitHub token 不应该具备对所有仓库的写权限
• .claude/settings.json 若含凭据,绝不入 git

带安全注意事项的完整精选 server 清单在 2026 年最佳 MCP server一文中。