Python MCP服务器入门模板
特性
- 使用以下工具实现MCP服务器
mcpPython SDK(FastMCP). - 暴露MCP 工具 （LLM可调用的函数）和 资源 （LLM可访问的数据）。
- 干净、模块化的架构
- 轻松注册工具和资源
- 具有可定制选项的命令行界面
- 已准备好进行生产部署
- 使用debugpy与VS Code集成的内置调试功能
- 配置开发工具（使用
uv用于环境/包管理） - Docker支持容器化部署
入门指南
先决条件
安装
- 克隆或用作模板： 获取代码。
git clone https://github.com/ltwlf/python-mcp-starter.git your-repo-name # Or use GitHub's "Use this template" button
cd your-repo-name- 重命名项目： 重命名核心组件：
- 重命名 hello_mcp_server 目录到您想要的Python包名称（例如。， my_awesome_mcp). - 搜索并替换 hello-mcp-server （in pyproject.toml, README.md, Dockerfile, docker-compose.yml)使用您的项目名称（例如。， my-awesome-mcp). - 搜索并替换 hello_mcp_server （在Python导入语句中，如 main.py, tests/test_server.py, pyproject.toml 脚本部分）使用您的新包名。 - 更新 APP_ID 在您的重命名中 server.py 文件。 - 更新 .vscode/launch.json 配置文件，以反映您的新项目和包名称。
- 创建虚拟环境：
# Create the virtual environment
uv venv
# Activate the environment (Windows PowerShell)
.venv\Scripts\Activate.ps1
# Or for other shells:
# source .venv/bin/activate (Linux/macOS)
# .venv\Scripts\activate.bat (Windows Command Prompt)- 安装依赖关系：
uv pip install -e ".[dev]"运行MCP服务器进行开发
您可以直接使用以下命令运行服务器 uv run 或 mcp SDK提供的CLI工具。这允许使用以下工具进行测试 MCP检查员.
在stdio模式下（用于MCP检查器）
方法1：使用 uv run
# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with the script name defined in your pyproject.toml
uv run your-script-name方法2：使用 mcp CLI工具
# Ensure your virtual environment is active first
# Replace 'hello_mcp_server' with your renamed package directory
mcp dev ./your_package_name/server.py在SSE模式下
# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with your script name
uv run your-script-name --sse或者使用自定义主机和端口：
# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with your script name
uv run your-script-name --sse --host 127.0.0.1 --port 9000Docker部署
更新 Dockerfile 和 docker-compose.yml 在构建之前反映重命名的项目/包。
# Build and run with Docker Compose
docker-compose up -d
# Or build and run directly with Docker
# Replace 'hello-mcp-server' with your image name
docker build -t your-image-name .
docker run -p 8000:8000 your-image-name发展
调试
此项目包括使用debugpy的内置调试功能。调试MCP服务器有两种主要方法：
使用调试模块
该项目包括一个专用的调试模块，使调试变得容易：
# Using uv (recommended)
uv run mcp-debug
首先连接到MCP检查器，连接后使用VS Code调试配置 附属于MCP工人 附加调试器进行调试
使用VS代码
VS代码调试配置了多种启动配置：
- 附属于MCP工人 -连接到运行中的MCP服务器（将其连接到运行的MCP调试）
- 启动MCP服务器（SSE） -使用服务器发送的事件直接启动MCP服务器
为了获得最佳体验：
- 首先，跑
uv run mcp-debug在终端中 - 然后，要设置断点，请使用具有“附加到MCP worker”配置的VS Code调试器
注： 确保您的虚拟环境已设置uv venv和uv pip install -e .[dev]在调试之前。
- 检查Python解释器：
- 确保VS Code在虚拟环境中使用了正确的Python解释器 - 如果需要，使用Python扩展的“select interpreter”命令选择解释器
要使用这些配置，请执行以下操作：
- 在VS Code中打开运行和调试面板（Ctrl+Shift+D）
- 从下拉列表中选择所需的配置
- 单击播放按钮或按F5
安全考虑
- 调试模式不应在生产环境中使用
- 调试器暴露了一个网络端口，如果不安全，该端口可能会被利用
- 始终在受信任的网络上使用调试或采取适当的安全措施
添加新工具
使用添加新工具 @mcp.tool() 室内装饰师 your_package_name/server.py:
# your_package_name/server.py
from mcp.server.fastmcp import FastMCP, Context
mcp = FastMCP("your-app-id") # Ensure APP_ID matches your project
# ... existing tools ...
# Add your new tool
@mcp.tool()
async def my_new_tool(param1: str, param2: int, ctx: Context) -> dict:
"""
Description of what your tool does.
Use the ctx object to report progress, log info, or read resources.
"""
ctx.info(f"Running my_new_tool with {param1=}, {param2=}")
# Tool implementation
result = f"Processed {param1} {param2} times"
await ctx.report_progress(1, 1) # Example progress
return {"result": result}添加新资源
使用添加新资源 @mcp.resource() 室内装饰师 your_package_name/server.py:
# your_package_name/server.py
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("your-app-id") # Ensure APP_ID matches your project
# ... existing resources ...
# Add resources
@mcp.resource("your-resource-uri")
def your_resource_func():
"""Returns application settings."""
return {"theme": "dark", "language": "en"}测试
确保中的导入语句 tests/test_server.py 指向您重命名的包。
pytest许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
致谢
- 主控程序 -微软的模型上下文协议
- MCP Python SDK -MCP的Python实现
- MCP检查员 -MCP通信检查工具
