MCP 服务器搭建 入门教程

如果你刚接触 MCP（Model Context Protocol），搭建第一个服务器可能会遇到概念不熟、配置出错、客户端连不上等问题。这篇教程会带你从零完成一个可运行的 MCP 服务器，涵盖环境准备、完整步骤、验证方法和常见错误排查，让你在 30 分钟内跑通基本流程。

Quick answer

MCP 服务器搭建的核心流程是：安装 Python 和 Node.js 环境 → 用 @modelcontextprotocol/server-sequential-thinking 或自定义脚本创建一个服务器 → 配置 MCP 客户端（如 Claude Desktop 或 VS Code 扩展）指向该服务器 → 启动并验证连通性。关键路径只有 5 步，但新手最容易在端口占用、JSON 配置格式和路径引用上出错。

下一步：MCP 服务器搭建 常见问题、mcp server 怎么搭建

Before you start

在动手之前，先确认以下三个条件。跳过任一都会导致后续步骤无法执行。

• Python 3.10+：MCP 官方 SDK 要求 Python 3.10 及以上。运行 python --version 检查，如果低于 3.10，需要先升级或使用 pyenv 管理版本。
• Node.js 18+：部分 MCP 服务器（如 server-filesystem）基于 Node.js 构建。用 node -v 确认版本。
• 一个支持 MCP 的客户端：主流选择是 Claude Desktop（需 2025 年 3 月后版本）或 VS Code 的 MCP 扩展（如 Continue）。两种客户端的配置方式略有差异，本教程以 Claude Desktop 为例。

如果你的系统是 Windows，建议在 WSL2（Ubuntu 22.04）中操作，避免路径分隔符和权限问题。macOS 和 Linux 可直接在终端进行。

Steps

1. 安装 MCP SDK

MCP 官方提供 Python 和 TypeScript 两种 SDK。对于入门，Python 版本更直观。

pip install "mcp[cli]"

安装完成后用 mcp --version 验证。如果提示找不到命令，检查 Python 的 bin 目录是否在 PATH 中 —— 这是新手最容易忽略的细节。

2. 编写第一个 MCP 服务器脚本

创建一个 Python 文件 weather_server.py，内容如下。这个服务器会返回一个简单的工具（工具名 get_forecast），供客户端调用。

from mcp.server import Server
from mcp.types import Tool, TextContent
import json

app = Server("weather-helper")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_forecast",
            description="返回指定城市的天气预报摘要",
            inputSchema={
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_forecast":
        city = arguments.get("city", "未知")
        # 真实场景会调用天气 API，此处仅做演示
        return [TextContent(type="text", text=f"{city} 今日天气：晴，25°C")]
    raise ValueError(f"未知工具: {name}")

if __name__ == "__main__":
    app.run(transport="stdio")

关键点：

• transport="stdio" 表示服务器通过标准输入输出与客户端通信，这是 MCP 最常用的传输方式。
• list_tools 告诉客户端服务器提供哪些能力，call_tool 处理实际调用。
• 输入 Schema 遵循 JSON Schema 规范，客户端会根据这个描述自动生成参数输入界面。

3. 配置客户端连接

在 Claude Desktop 的配置文件 claude_desktop_config.json 中添加 MCP 服务器定义。文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "weather-helper": {
      "command": "python",
      "args": ["/path/to/your/weather_server.py"]
    }
  }
}

command 和 args 的组合等价于在终端执行 python /path/to/your/weather_server.py。路径必须使用绝对路径，不要用 ~ 或相对路径，否则客户端会找不到文件。

如果服务器依赖虚拟环境，args 中需要指向虚拟环境中的 Python：

{
  "mcpServers": {
    "weather-helper": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/your/weather_server.py"]
    }
  }
}

4. 启动并测试

重启 Claude Desktop，然后在聊天框中输入：

使用天气工具查看北京的天气

如果配置正确，Claude 会主动调用 get_forecast 工具并返回结果。你应当看到类似“北京 今日天气：晴，25°C”的回复。

5. 验证服务器状态

Claude Desktop 会为每个 MCP 服务器在日志中记录启动和错误信息。日志位置：

• macOS：~/Library/Logs/Claude/mcp-server-weather-helper.log
• Windows：%APPDATA%\Claude\logs

打开日志文件，如果看到 MCP server started 且没有 ERROR 行，说明连接成功。如果日志为空或只有启动行，可以在终端中手动测试：

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python weather_server.py

正常输出应包含 "name":"get_forecast" 的 JSON 响应。如果没有任何输出或报错，说明服务器脚本本身有问题。

Checks

配置完成后，用这个检查清单快速确认每个环节：

• 环境检查：python --version ≥ 3.10；pip list | grep mcp 能列出 mcp 包。
• 文件检查：服务器脚本路径与 config 中的路径完全一致（含大小写）。用 ls -l /path/to/weather_server.py 确认文件存在。
• 格式检查：claude_desktop_config.json 必须是合法 JSON。用 python -m json.tool claude_desktop_config.json 验证。
• 端口检查：虽然 stdio 模式不占 TCP 端口，但如果你后续使用 SSE 传输模式（详见 MCP 传输方式对比），确保 8000（默认）未被占用：lsof -i :8000。
• 日志检查：打开最新日志文件，搜索 connected 或 error 关键词。

Troubleshooting

下面是搭建过程中最常见的 3 个问题及对应处理方式。

客户端不显示工具按钮

症状：Claude 聊天界面没有出现工具图标或无法调用工具。

最常见原因：config 文件 JSON 格式错误。用在线 JSON 验证器或 python -m json.tool 检查。特别注意：

• 键名 mcpServers 的 S 是大写
• 每个服务器名称下的 command 和 args 不能缺失
• 不要在最后一项后面加逗号

如果格式正确，重启 Claude Desktop 并清理缓存：

• macOS：删除 ~/Library/Application Support/Claude/CachedData
• Windows：删除 %APPDATA%\Claude\CachedData

服务器启动后自动退出

症状：Claude 日志中出现 MCP server exited 或进程号一闪而过。

原因通常是 Python 脚本抛出异常。在终端中手动运行服务器脚本，观察是否有报错：

python /path/to/weather_server.py

如果看到 ModuleNotFoundError，说明依赖未安装；如果是 SyntaxError，检查 Python 版本是否 >= 3.10。

临时解决：在脚本开头添加 import sys; print("started", flush=True)，这样可以确认脚本是否执行到了 app.run()。

工具调用返回错误

症状：Claude 正常调用了工具，但返回“工具调用失败”或空结果。

检查 call_tool 函数的返回结构。MCP 规定返回必须是 list[TextContent] 类型，不能直接返回字符串或其他类型。一个容易犯的错误是忘记用 TextContent 包裹文本。

# 错误写法
return f"{city} 天气：晴"

# 正确写法
return [TextContent(type="text", text=f"{city} 天气：晴")]

如果工具需要接收参数但客户端传的是空参，检查 inputSchema 中 required 字段是否缺失。

FAQ

MCP 服务器搭建 入门教程 是什么？

这是一份面向零基础用户的实践指南，讲解如何从环境配置开始，到完成一个可被 AI 客户端调用的 MCP 服务器。MCP 服务器本质上是运行在本地的轻量进程，通过标准输入输出或 HTTP 与 AI 应用通信，提供工具。

如何进阶学习 MCP 服务器开发？

完成本教程后，可以参考 [