Python MCP Server Starter Template

Python MCP 服务启动模板

一个模板仓库，用于使用 Model Context Protocol (MCP) 和 MCP Python SDK 创建 Python 应用程序。

功能

• 使用 mcp Python SDK（FastMCP）实现 MCP 服务。
• 提供 MCP 工具（可由大模型调用的函数）和 资源（大模型可访问的数据）。
• 架构清晰、模块化
• 轻松注册工具和资源
• 提供带自定义选项的命令行界面
• 可用于生产环境部署
• 内置基于 debugpy 的调试功能，并集成 VS Code
• 配置开发工具（使用 uv 管理环境和包）
• 支持 Docker 容器化部署

开始使用

先决条件

• Python 3.10 或更高版本
• uv（推荐用于环境和包管理）
• MCP Inspector（推荐用于测试和调试 MCP 服务的可视化工具）
• [可选] Git
• [可选] 用于容器化部署的 Docker

安装

1. 克隆或用作模板： 获取代码。

   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
   

2. 重命名项目： 重命名核心组件：

   • 将 hello_mcp_server 目录重命名为你想要的 Python 包名称（例如，my_awesome_mcp）。
   • 在 pyproject.toml、README.md、Dockerfile、docker-compose.yml 中搜索并替换 hello-mcp-server，替换为你的项目名称（例如，my-awesome-mcp）。
   • 在 Python 导入语句（例如 main.py、tests/test_server.py 和 pyproject.toml 的 scripts 部分）中搜索并替换 hello_mcp_server，替换为新的包名称。
   • 更新重命名后的 server.py 文件中的 APP_ID。
   • 更新 .vscode/launch.json 配置文件，使其反映新的项目名称和包名称。

3. 创建虚拟环境：

   # 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)
   

4. 安装依赖项：

   uv pip install -e ".[dev]"
   

在开发环境中运行 MCP 服务

你可以直接使用 uv run 或 SDK 提供的 mcp CLI 工具运行服务。这样便可以使用 MCP Inspector 等工具进行测试。

在 stdio 模式下（用于 MCP Inspector）

方法 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 9000

Docker 部署

构建前，请更新 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 Inspector；连接后，使用 VS Code 调试配置 Attach to MCP worker 连接调试器进行调试

使用 VS Code

VS Code 调试已配置多个启动配置：

1. 附加到 MCP worker - 附加到正在运行的 MCP 服务（将此配置附加到正在运行的 mcp-debug）
2. 启动 MCP 服务（SSE） - 直接启动支持服务器发送事件的 MCP 服务

为获得最佳体验：

1. 首先，在终端中运行 uv run mcp-debug
2. 然后，若要设置断点，请使用 VS Code 调试器中的“附加到 MCP worker”配置

注意： 调试前，请确保已使用 uv venv 和 uv pip install -e .[dev] 设置虚拟环境。

3. 检查 Python 解释器：
   • 确保 VS Code 使用虚拟环境中的正确 Python 解释器
   • 如有需要，可使用 Python 扩展的“选择解释器”命令来选择解释器

使用这些配置：

1. 在 VS Code 中打开“运行和调试”面板（Ctrl+Shift+D）
2. 从下拉菜单中选择所需的配置
3. 点击播放按钮或按 F5

安全注意事项

• 切勿在生产环境中使用调试模式
• 调试器会开放一个网络端口，如果未采取安全措施，该端口可能遭到利用
• 始终在可信网络中进行调试，或采取适当的安全措施

添加新工具

在 your_package_name/server.py 中使用 @mcp.tool() 装饰器添加新工具：

# 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}

添加新资源

在 your_package_name/server.py 中使用 @mcp.resource() 装饰器添加新资源：

# 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 许可证授权，详情请参阅 LICENSE 文件。

致谢

• MCP - Microsoft 推出的 Model Context Protocol
• MCP Python SDK - MCP 的 Python 实现
• MCP Inspector - 用于检查 MCP 通信的工具