星战科技xingzhan.cloud
返回市场
MCP服务器模板

MCP服务器模板

作者：pietroperona18 星标更新：2025-07-04
安装使用来源：spider==github.com

项目介绍

<div align="center"> <img src="assets/mcp_server_logo.svg" alt="MCP Server Template" width="450"/> </div> <br/> <br/>

Python 3.11+ FastMCP Claude AI Deploy to Render

一个实用的Cookiecutter模板，用于构建连接Claude AI到外部API的MCP服务器。使用FastMCP构建，并准备好在Render.com上部署。

Deploy to Render

主要功能

  • 多平台兼容性：适用于Claude Desktop、Claude Web和Claude API
  • 全面的身份验证支持：API密钥、Bearer Token、OAuth2、基本身份验证
  • 速率限制：可配置请求节流以避免达到API限制
  • 即用工具：6个预建的通用API工具，可适应任何服务
  • 一键部署：与Render.com集成并预先配置设置
  • Docker支持：云部署容器化（测试版 - 欢迎社区测试）
  • 强大的错误处理：详细的错误报告和恢复
  • 可测试组件：每个模块都可以独立测试
  • 会话管理：防止“事件循环已关闭”错误

功能概述

此模板生成一个完整的MCP服务器项目，使Claude AI能够与任何API交互。可以将其视为连接Claude和您想要使用的外部服务之间的桥梁。

示例场景：

  • 来自气象服务的天气数据
  • 来自新闻API的新闻头条
  • 来自金融数据提供商的股票价格
  • 来自平台API的社交媒体帖子
  • 来自市场API的电子商务数据

技术栈

要求：Python 3.11或更新版本

快速开始

1. 生成您的项目

pip install cookiecutter
cookiecutter https://github.com/pietroperona/mcp-server-template

您将被询问一些问题：

project_name: 新闻API服务器
project_slug: news-api-server  [自动生成]
author_name: 您的名字
author_email: you@example.com
github_username: yourusername
api_base_url: https://newsapi.org/v2
api_service_type: REST API
auth_type: API密钥
include_rate_limiting: 是
include_caching: 否
render_deployment: 是
docker_support: 是
license: MIT

2. 配置您的API

cd news-api-server
cp .env.example .env

编辑.env文件，添加您的API凭证：

API_BASE_URL=https://newsapi.org/v2
API_KEY=your_news_api_key

3. 安装并运行

pip install -r requirements.txt
python main.py

您的MCP服务器现在正在http://localhost:8000运行。

4. 连接到Claude Desktop

在您的Claude Desktop MCP配置中添加以下内容：

{
  "mcpServers": {
    "news-api": {
      "command": "python",
      "args": ["news-api-server/main.py"],
      "cwd": "news-api-server"
    }
  }
}

现在Claude可以获取新闻：“最新的科技头条是什么？”

5. 连接到Claude Web浏览器（Claude.ai）

您的MCP服务器还公开了一个SSE（服务器发送事件）端点/sse，可以在浏览器中的Claude Web中使用：

  1. 将您的MCP服务器部署到公共URL（参见部署部分）
  2. 在Claude Web中，转到设置 → Claude API工具
  3. 添加您的MCP服务器的公共URL + /sse端点： 
    https://your-mcp-server.onrender.com/sse
  4. Claude Web将在工具菜单中显示您的工具

注意：/sse端点自动包含在此模板生成的所有MCP服务器中。

您将获得什么

每个生成的项目包括：

6个即用工具

  • get_api_status - 检查您的API是否正常工作
  • list_resources - 浏览可用的数据（文章、用户、产品等）
  • get_resource_by_id - 获取特定项目的详细信息
  • create_resource - 添加新数据
  • update_resource - 修改现有数据
  • delete_resource - 删除数据

实际示例：新闻API

当您问Claude“展示最近的技术新闻”，会发生以下情况：

  1. Claude调用list_resources(resource_type="articles", category="technology")
  2. 您的MCP服务器访问https://newsapi.org/v2/everything?q=technology
  3. Claude获取新闻数据并以格式化的文章形式回应

项目结构

news-api-server/
├── core/
│   ├── config.py     # API凭证及设置
│   ├── auth.py       # 处理API认证
│   └── client.py     # 带重试机制的HTTP客户端
├── tools/
│   └── example_tools.py  # 6个MCP工具
├── docs/             # 设置指南及故障排除
│   ├── configuration.md  # 详细的配置选项
│   ├── quick-start.md    # 快速入门指南
│   ├── README.md         # 文档概览
│   └── troubleshooting.md # 常见问题及解决方案
├── main.py          # FastMCP服务器
└── .env.example     # 配置模板

注意：当您的服务器运行时，可能会创建以_data/结尾的目录（如cache_data/）。这些目录通过.gitignore自动排除，因为它们包含不应提交的运行时数据。

身份验证支持

模板处理不同的身份验证方法：

API密钥（最常见）

API_KEY=your_key_here
API_KEY_HEADER=X-API-Key

Bearer Token

BEARER_TOKEN=your_token_here

OAuth2（针对复杂API）

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

基本身份验证

USERNAME=your_username
PASSWORD=your_password

生产部署

Render.com（推荐）

  1. 将生成的项目推送到GitHub
  2. 连接到Render.com
  3. 设置环境变量
  4. 您的MCP服务器上线！

模板包括带有生产优化设置的render.yaml。

重要提示：对于Claude Web浏览器，请确保记录下您部署的服务的公共URL。Claude Web将通过/sse端点连接到您的MCP服务器：

https://your-service-name.onrender.com/sse

Docker

注意：Docker支持包含在此模板中，但尚未经过广泛测试。欢迎社区反馈和贡献。

docker build -t my-mcp-server .
docker run -p 8000:8000 --env-file .env my-mcp-server

对于Claude Web：访问SSE端点http://your-docker-host:8000/sse

现实世界示例

新闻头条服务

# 生成项目
cookiecutter https://github.com/pietroperona/mcp-server-template
# 项目：新闻API服务器
# API：NewsAPI.org（免费层）
# 结果：Claude可以根据类别/关键词获取最新新闻

尝试一下：NewsAPI.org - 每天1000次免费请求

天气服务

# 生成项目
cookiecutter https://github.com/pietroperona/mcp-server-template
# 项目：天气API服务器
# API：OpenWeatherMap（免费）
# 结果：Claude可以查询全球天气

尝试一下：OpenWeatherMap - 免费API，每天1000次调用

股票市场数据

# 生成项目
cookiecutter https://github.com/pietroperona/mcp-server-template
# 项目：股市服务器
# API：Alpha Vantage（免费）
# 结果：Claude可以查询股票价格和市场数据

尝试一下：Alpha Vantage - 免费API密钥，每分钟5次调用

社交媒体整合

# 生成项目
cookiecutter https://github.com/pietroperona/mcp-server-template
# 项目：社交媒体服务器
# API：Twitter/X API（付费）
# 结果：Claude可以发布推文并阅读社交媒体动态

详细设置示例

让我们逐步构建一个新闻API服务器：

1. 获取NewsAPI密钥

  • 访问newsapi.org
  • 注册免费账户
  • 复制您的API密钥

2. 生成项目

cookiecutter https://github.com/pietroperona/mcp-server-template

project_name: 新闻API服务器
project_slug: news-api-server
author_name: John Smith
api_service_type: REST API
auth_type: API密钥
api_base_url: https://newsapi.org/v2
include_rate_limiting: 是
render_deployment: 是

3. 配置环境

cd news-api-server
cp .env.example .env

编辑.env：

API_BASE_URL=https://newsapi.org/v2
API_KEY=your_actual_api_key_here
API_KEY_HEADER=X-API-Key

4. 测试您的服务器

python main.py

5. 使用Claude进行测试

询问Claude：“最新的科技头条是什么？”

Claude将使用您的工具：

工具：list_resources
参数：resource_type="articles", category="technology"
结果：最新的科技新闻文章标题、描述和链接

自定义

为您的API修改

生成的工具是通用的，但易于定制：

# 在tools/example_tools.py中
async def list_resources_async(resource_type: str = "articles", category: str = "general"):
    # 根据您的API进行定制
    endpoint = f"/everything?category={category}"
    response = await client.get(endpoint)
    return response

添加API特定工具

@mcp.tool()
def get_headlines_by_category(category: str, country: str = "us") -> str:
    """根据类别和国家获取头条新闻"""
    result = run_async_tool(get_headlines_async, category, country)
    return json.dumps(result, indent=2)

配置速率限制

# 在.env中
RATE_LIMIT_REQUESTS=60    # 60次请求
RATE_LIMIT_WINDOW=60      # 每分钟

故障排除

身份验证问题

“身份验证失败”

  • 检查您的API密钥是否正确
  • 验证API_KEY_HEADER名称
  • 首先在浏览器/Postman中测试API密钥

工具连接问题

“工具未出现在Claude中”

  • 重启Claude Desktop
  • 检查MCP配置语法
  • 确认服务器启动无误

“Claude Web未显示我的工具”

  • 确保您使用了正确的/sse端点
  • 如果托管在自定义域名上，检查CORS设置
  • 确认您的服务器对公众可访问

API连接问题

“连接超时”

  • 在.env中增加API_TIMEOUT
  • 检查互联网连接
  • 验证API端点URL

“API版本化问题”

  • 有些API不使用URL中的版本前缀
  • 在您的.env文件中设置API_VERSION=none或留空
  • 此模板自动处理无版本的API

技术问题

“事件循环已关闭”错误

  • 这已在最新模板版本（2025年7月）中修复
  • 模板现在采用更好的会话管理方法来处理aiohttp
  • 每个请求都会创建一个新的会话并进行适当的清理
  • 自定义事件循环处理防止这些错误

开发

运行测试

python core/auth.py      # 测试身份验证
python core/client.py    # 测试API连接
python main.py           # 启动MCP服务器

调试模式

DEBUG=true python main.py

显示详细的请求/响应日志。

会话管理

此模板采用优化的方法来管理aiohttp会话：

# 为每个请求创建一个新的会话（防止“事件循环已关闭”错误）
async with aiohttp.ClientSession() as session:
    async with session.request(...) as response:
        # 处理响应

这种模式确保：

  • 每个HTTP请求都获得一个新的会话
  • 会话在使用后被正确关闭
  • 不会出现“事件循环已关闭”错误
  • 更好的处理asyncio事件循环

已知限制

  • Docker支持：虽然包含了Dockerfile和docker-compose文件，但Docker部署尚未在不同环境中广泛测试。我们欢迎社区反馈和测试。
  • OAuth2流程：OAuth2实现需要手动交换令牌 - 自动基于浏览器的流程尚未实现。

贡献

  1. 分叉仓库
  2. 使用不同类型的API测试您的更改
  3. 更新文档
  4. 提交拉取请求

为什么选择这个模板？

构建MCP服务器涉及大量样板代码：

  • 身份验证处理
  • 错误管理
  • 速率限制
  • 配置
  • 部署设置

此模板立即为您提供所有这些功能，因此您可以专注于连接到您特定的API。

基于经过验证的工具：FastMCP用于MCP框架，模型上下文协议用于Claude集成。

适用于：

  • Claude Desktop（通过本地MCP服务器）
  • Claude Web浏览器（通过/sse端点）
  • Claude API（通过代理配置）

许可

MIT许可 - 可用于任何目的，商业或个人用途。

最近更新

  • 2025年7月：通过改进的aiohttp会话管理修复了“事件循环已关闭”错误
  • 2025年7月：通过/sse端点增加了对Claude Web浏览器的支持
  • 2025年7月：通过更好地处理无版本的API改进了API版本化
  • 2025年7月：增加了更好的错误处理和故障排除指导

准备将Claude连接到您最喜欢的API了吗？

pip install cookiecutter
cookiecutter https://github.com/pietroperona/mcp-server-template