Linux 服务器 Python 版 MCP 服务部署整体方案（适配 Claude/Cursor/自研Agent）

Linux 服务器 Python 版 MCP 服务部署整体方案（适配 Claude/Cursor/自研Agent）

一、方案概述

1.1 适用场景

服务端：Linux 服务器（Ubuntu/CentOS/麒麟系统），基于Python官方MCP SDK自定义开发MCP服务

客户端：Claude Desktop、Cursor、自研AI Agent

部署模式：兼顾本地调试（STDIO）、跨网生产服务（Streamable HTTP），满足开发+生产全场景需求

1.2 技术选型

开发语言：Python 3.10+（推荐3.11）

核心依赖：官方标准 mcp Python SDK

传输协议：STDIO（本地进程调用）、Streamable HTTP（生产远程调用，替代传统SSE，支持双向流式通信）

运维方案：Systemd 常驻进程、开机自启、日志监控

调试工具：官方 MCP Inspector 可视化调试

1.3 方案优势

纯官方协议，兼容性强，适配所有主流MCP客户端

环境独立隔离，无系统依赖冲突

支持多客户端同时接入，自研Agent可直接对接协议接口

服务稳定常驻，异常自动重启，满足生产运行要求

二、前置环境部署

2.1 安装Python环境

统一安装 Python3.11 及虚拟环境组件，适配MCP SDK最低版本要求

Ubuntu 系统

|-----------------------------------------------------------------------|
| bash apt update apt install python3.11 python3-pip python3.11-venv -y |

CentOS/麒麟系统

|-----------------------------------------------|
| bash yum install python3.11 python3.11-pip -y |

2.2 初始化独立运行环境

创建专属目录+虚拟环境，隔离项目依赖，避免系统环境冲突

|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| bash # 创建项目目录 mkdir -p /opt/mcp-python cd /opt/mcp-python # 初始化虚拟环境 python3.11 -m venv venv source venv/bin/activate # 升级pip并安装官方MCP SDK pip install --upgrade pip pip install mcp |

三、双模式MCP服务搭建

3.1 模式一：STDIO 本地调试模式（仅本机客户端调用）

3.1.1 服务源码（stdio_server.py）

适用于Linux本机安装的Cursor/Claude调试，无需开放端口，安全性高

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| python from mcp.server import Server import mcp.types as types import mcp.server.stdio import asyncio # 初始化MCP服务实例 app = Server("python-mcp-stdio") # 自定义测试工具 @app.tool(name="hello", description="MCP测试工具，返回问候信息") async def hello(name: str) -> list $types.TextContent$ : return $types.TextContent(type="text", text=f"Hello {name}! Python MCP STDIO服务调用成功")$ async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await app.run( read_stream, write_stream, app.create_initialization_options() ) if name == "main": asyncio.run(main()) |

3.1.2 客户端配置（Claude/Cursor）

配置文件写入虚拟环境Python绝对路径，保证依赖正常加载

Claude Desktop 配置（claude_desktop_config.json）

|-------------------------------------------------------------------------------------------------------------------------------------------------|
| json { "mcpServers": { "python-mcp-stdio": { "command": "/opt/mcp-python/venv/bin/python3", "args": $"/opt/mcp-python/stdio_server.py"$ } } } |

Cursor 配置（.cursor/mcp.json）

配置内容与Claude一致，保存后完全重启客户端生效

3.2 模式二：Streamable HTTP 生产远程模式（推荐）

支持跨网络访问，适配Windows/Mac客户端、自研Agent多端同时接入，为生产唯一推荐模式

3.2.1 服务源码（http_server.py）

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| python from mcp.server import Server import mcp.types as types from mcp.server.streamable_http import run_streamable_http_server # 初始化服务 app = Server("python-mcp-http") # 自定义工具1：基础问候测试 @app.tool(name="hello", description="基础测试工具，验证服务连通性") async def hello(name: str) -> list $types.TextContent$ : return $types.TextContent(type="text", text=f"Hello {name}! Linux Python MCP远程服务调用成功")$ # 自定义工具2：数值计算（可自行扩展业务工具） @app.tool(name="add", description="两数相加计算工具") async def add(a: float, b: float) -> list $types.TextContent$ : return $types.TextContent(type="text", text=f"计算结果：{a + b}")$ def main(): # 监听0.0.0.0允许外网访问，端口8120，接口路径/mcp run_streamable_http_server( app, host="0.0.0.0", port=8120, path="/mcp" ) if name == "main": main() |

3.2.2 端口放行

云服务器需同步放行防火墙+安全组8120端口

Ubuntu

|-------------------------|
| bash ufw allow 8120/tcp |

CentOS/麒麟

|-------------------------------------------------------------------------|
| bash firewall-cmd --add-port=8120/tcp --permanent firewall-cmd --reload |

3.2.3 Systemd 常驻服务配置（生产必备）

实现开机自启、异常自动重启、后台永久运行

创建服务文件：/etc/systemd/system/mcp-python-http.service

启动并设置开机自启

|--------------------------------------------------------------------------------------------------------------------------------|
| bash systemctl daemon-reload systemctl enable mcp-python-http systemctl start mcp-python-http systemctl status mcp-python-http |

日志查看（实时监控）

|---------------------------------------|
| bash journalctl -u mcp-python-http -f |

四、全客户端接入配置

4.1 Claude Desktop 接入配置

修改 claude_desktop_config.json，替换为服务器公网IP

|-----------------------------------------------------------------------------------|
| json { "mcpServers": { "linux-python-mcp": { "url": "http://服务器IP:8120/mcp" } } } |

4.2 Cursor 接入配置

编辑 .cursor/mcp.json，配置与Claude一致，重启客户端生效

4.3 自研Agent 接入方案

基于官方SDK快速对接Streamable HTTP协议，无需手动解析JSON-RPC报文

五、服务调试方案

使用官方 MCP Inspector 可视化调试，快速排查协议、工具调用异常

|---------------------------------------------------------------------------------------|
| bash # 调试远程HTTP MCP服务 npx @modelcontextprotocol/inspector --url http://服务器IP:8120/mcp |

执行后打开浏览器可视化界面，可查看服务工具列表、报文收发、错误日志

六、生产环境安全优化

禁止公网裸端口暴露：配置Nginx反向代理，启用HTTPS加密传输

增加接口鉴权：改造服务端代码，增加Bearer Token校验，防止未授权访问

权限管控：严格限制MCP工具权限，禁止系统高危操作、根目录文件读写

日志审计：开启服务日志持久化，记录所有工具调用记录，便于溯源排查

基础Nginx反向代理配置片段：

|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| nginx location /mcp { proxy_pass http://127.0.0.1:8120/mcp; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_set_header Host $host; proxy_set_header X-Real-IP$ remote_addr; proxy_buffering off; } |

七、常见问题排查

客户端无法连接服务：检查服务监听地址为0.0.0.0、服务器防火墙/云安全组端口已放行

配置不生效 ：Claude/Cursor需完全退出重启，最小化窗口不会加载新配置

模块缺失报错：必须使用虚拟环境内的Python解释器，不可使用系统默认Python

协议调用失败：客户端URL路径必须与服务端/mcp路径完全一致

八、方案总结

本方案基于Python官方MCP SDK，搭建了适配全客户端的标准化MCP服务，通过STDIO模式满足本地开发调试，Streamable HTTP模式支撑生产跨网调用，搭配Systemd常驻、可视化调试、安全加固能力，可直接用于正式业务环境，同时支持自研Agent深度对接和自定义工具扩展。