SELF-DEPLOYMENT · v1.0

自部署指南

你下载的 zip 是一份独立、可运行的 MCP Server,完全可以在网关之外自部署 —— 本机 pip install + python 起,或 Docker 容器化跑,或嵌进 Claude Desktop。 本页按部署路径展开,讲清楚每一步要做什么、踩什么坑。

一、zip 里有什么

文件作用必备?
mcp_server.py MCP Server 主体,含全部工具函数,启动入口 ✅ 必备
requirements.txt Python 依赖清单(mcp[cli] / httpx / uvicorn) ✅ 必备
Dockerfile 容器镜像配方,基于 python:3.11-slim 仅 Docker 部署用
tools.json 工具定义的数据副本(参考用,运行时从代码读) 📖 参考
config.yaml 配置参考(实际以环境变量为准) 📖 参考
README.md 每个 zip 自带的简要说明 📖 参考

二、环境变量一览

所有变量都是可选的,有合理默认值,只有 USER_API_ENDPOINT 几乎一定要设:

变量含义默认何时必设
USER_API_ENDPOINT 你业务 API 的根 URL wizard 第 3 步填写的值 几乎总是
API_KEY 鉴权 Key,会作为 X-API-Key 头转发 不发送 鉴权方式选 api_key 时
HOST streamable-http 绑定的 host 127.0.0.1 对外服务时改 0.0.0.0
PORT streamable-http 监听端口 8000 端口被占时
TOOL_TIMEOUT 单次工具调用总超时(秒) wizard 生成的默认值 上游 API 慢时调大
TOOL_CONNECT_TIMEOUT TCP 连接超时(秒) wizard 生成的默认值 极少需要改

三、本机直接跑

3.1 Streamable HTTP 模式

适合做 HTTP 服务暴露给多客户端(Cherry Studio / Cursor / Web)。

# 1. 解压
unzip my-agent.zip -d my-agent
cd my-agent

# 2. 装依赖(一次性,建议用虚拟环境)
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. 配环境变量
export USER_API_ENDPOINT="https://api.example.com"
export API_KEY="sk-xxxxxx"          # 没设鉴权就跳过
export HOST="0.0.0.0"                # 0.0.0.0 才能被局域网/外部访问
export PORT="8080"

# 4. 跑
python mcp_server.py

看到 Uvicorn running on http://0.0.0.0:8080 就起来了。客户端接 http://<your-ip>:8080/mcp。

3.2 Stdio 模式

适合嵌进 Claude Desktop 这类用 stdio 与本地进程通信的客户端。

cd my-agent
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export USER_API_ENDPOINT="https://api.example.com"
# 不用启,Claude Desktop 会按 mcp.json 配置拉起 python 进程

后续接入 Claude Desktop 见 客户端接入指南。

四、Docker 部署

zip 自带 Dockerfile,直接 build 即可:

# 1. 把整个 zip 内容放到一个目录
unzip my-agent.zip -d my-agent && cd my-agent

# 2. 构造镜像
docker build -t my-agent .

# 3. 跑容器(streamable-http)
docker run -d --name my-agent \
  -p 8080:8080 \
  -e USER_API_ENDPOINT="https://api.example.com" \
  -e API_KEY="sk-xxxxxx" \
  my-agent

# 4. 看日志确认起来
docker logs -f my-agent

# 5. 客户端接 http://<docker-host>:8080/mcp

stdio 模式没有 EXPOSE 端口,容器靠 stdin/stdout 通信 —— 适合被 docker compose 或 K8s 当 sidecar 拉起:

docker run -i --rm \
  -e USER_API_ENDPOINT="https://api.example.com" \
  my-agent

注:-i 必须开,否则容器拿不到 stdin。

五、Claude Desktop 接入(stdio 模式)

编辑 mcp.json(macOS: ~/.config/claude/mcp.json;Windows: %APPDATA%\Claude\mcp.json):

{
  "mcpServers": {
    "my-agent": {
      "command": "python",
      "args": ["C:/Users/you/my-agent/mcp_server.py"],
      "env": {
        "USER_API_ENDPOINT": "https://api.example.com",
        "API_KEY": "sk-xxxxxx"
      }
    }
  }
}

重启 Claude Desktop,在工具列表里会看到 my-agent 暴露的全部工具。

Windows 路径注意:args 里要写绝对路径,且反斜杠要转义("C:\\Users\\you\\...")或直接用正斜杠。

六、常见问题

Q1: 启动报 ModuleNotFoundError: No module named 'mcp'

忘了 pip install -r requirements.txt。如果用了虚拟环境,确认 Claude Desktop 的 command 指向虚拟环境的 python(否则它会调系统 python,找不到包):

# 找虚拟环境里的 python 绝对路径
which python          # macOS/Linux
where python          # Windows
# 把这个绝对路径写进 mcp.json 的 command 字段

Q2: Uvicorn running on http://127.0.0.1:8080 但外部连不上

默认 HOST=127.0.0.1 只接受本机连接。设 HOST=0.0.0.0 即可对外。

Q3: 工具调用一直超时

调大 TOOL_TIMEOUT(默认约 30s):

export TOOL_TIMEOUT=120

Q4: Docker 容器起不来,docker logs 看到 Address already in use

宿主机 8080 被占。换端口映射:

docker run -p 9000:8080 ... my-agent

客户端连 http://<host>:9000/mcp。

Q5: 想加新工具,不想再跑一遍 wizard

直接编辑 mcp_server.py — 用 @mcp.tool() 装饰器新加一个异步函数即可。改完重启服务生效。

七、和网关托管模式的区别

维度网关托管自部署
冷启动 网关里 in-process 加载(几十 ms) 本机或容器冷启(几百 ms ~ 几秒)
URL 稳定性 网关重启 restore_running_servers 恢复,URL 不变 自己起进程,URL 取决于 HOST:PORT
多用户隔离 网关按 user_id 隔离,可多账号 单租户,你自己控访问
鉴权 / 配额 网关侧可加 IP 白名单 / 速率限制 依赖反代(Nginx)或 K8s NetworkPolicy
代码再编辑 得重新走 wizard 直接 vim 改 mcp_server.py
适用场景 快速验证、多用户协作 生产部署、深度定制、嵌入现有系统

还没看够?回到 使用指导 看完整流程,或 翻 客户端接入指南 配 IDE / Cherry Studio。

📦 只想用 Docker? 跳到 用 Docker 跑 MCP Server, 那页专注容器化: docker build / compose 编排 / Claude Desktop sidecar / 反代 / 镜像优化, 比本页的第四节更详细。