AI导哈

MCP服务器模板

基于FastAPI和FastMCP的MCP服务器模板，支持快速开发高效的MCP服务器。

  • by joonheeu
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 joonheeu/mcp-server-template

使用说明

MCP服务器模板

此项目是使用FastAPI和FastMCP的模型上下文协议（MCP）服务器模板。结合Python+uv+FastMCP+FastAPI+Scalar UI，支持快速高效的MCP服务器开发。

🚀 开始

1.创建和激活虚拟环境

uv使用创建并激活Python虚拟环境：

# uv 사용 (권장)
uv venv
source .venv/bin/activate  # Linux/macOS
# 또는 .venv\Scripts\activate  # Windows

# 또는 기존 venv 사용
python -m venv .venv
source .venv/bin/activate

2.安装依赖性

# uv 사용 시 (권장)
uv pip install -r requirements.txt

# 또는 pyproject.toml 사용
uv sync

# pip 사용 시
pip install -r requirements.txt

3.设置环境变量

env.example 复制文件 .env 创建文件：

cp env.example .env

创建的 .env 打开文件设置所需的环境变量：

# Server Configuration
SERVER_NAME=my-awesome-mcp-server
SERVER_VERSION=1.0.0
SERVER_DESCRIPTION="My awesome MCP server"

# API Configuration
API_HOST=localhost
API_PORT=8001

# External API Configuration (실제 API에 맞게 수정)
EXTERNAL_API_KEY=your_actual_api_key
EXTERNAL_API_SECRET=your_actual_api_secret
EXTERNAL_API_BASE_URL=https://your-api.example.com

🖥️ 运行服务器

以开发模式运行

# uvicorn으로 실행 (hot reload 포함)
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

# 또는 Python으로 직접 실행
python -m app.main

以生产模式运行

uvicorn app.main:app --host 0.0.0.0 --port 8001

服务器运行后，可以访问以下URL：

  • 标量UI: http://localhost:8001/scalar （推荐）
  • Swagger用户界面: http://localhost:8001/docs
  • MCP SSE端点: http://localhost:8001/mcp/sse
  • 健康检查: http://localhost:8001/health

📂 项目结构

mcp-server-template/
├── app/                          # 메인 애플리케이션 코드
│   ├── main.py                   # FastAPI 앱 및 MCP 서버 설정
│   ├── config.py                 # 환경 변수 및 설정 관리
│   └── services/                 # 외부 서비스 연동 로직
│       └── example_api_client.py # 예시 API 클라이언트
├── static/                       # 정적 파일
│   └── scalar.html              # Scalar UI HTML
├── docs/                        # 문서 (선택사항)
├── pyproject.toml               # uv/Python 프로젝트 설정
├── requirements.txt             # Python 의존성 목록
├── env.example                  # 환경 변수 예시
└── README.md                    # 프로젝트 문서

🔗 MCP（模型上下文协议）사용

从MCP客户端连接

在MCP客户端配置文件中添加以下内容：

{
  "mcpServers": {
    "My MCP Server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:8001/sse"
      ]
    }
  }
}

支持的MCP工具

此模板提供了基本的MCP工具：

  • get_data_by_id：使用数据ID查询特定数据
  • search_data_by_query：使用关键字搜索数据
  • 创建新数据：创建新数据
  • update_现有数据：更新现有数据
  • 删除数据_by_id：删除数据

🛠️ 自定义

1.修改API客户端

app/services/example_api_client.py 将文件修改为实际使用的外部API：

# 실제 API 엔드포인트 및 인증 방식에 맞게 수정
class YourAPIClient:
    def __init__(self):
        self.base_url = "https://your-api.example.com"
        self.api_key = "your-api-key"
    
    async def your_custom_method(self, param: str):
        # 실제 API 호출 로직 구현
        pass

2.添加MCP工具

app/main.py可以在中添加新的MCP工具：

@mcp.tool(description="새로운 기능을 수행합니다.")
async def new_tool(param: str) -> str:
    """새로운 도구 설명"""
    try:
        # 실제 로직 구현
        result = {"message": f"처리 완료: {param}"}
        return json.dumps(result, indent=2, ensure_ascii=False)
    except Exception as e:
        return json.dumps({"error": str(e)}, indent=2, ensure_ascii=False)

3.添加FastAPI端点

您还可以轻松添加REST API端点：

@app.get("/new-endpoint", tags=["Custom"])
async def new_endpoint():
    """새로운 REST API 엔드포인트"""
    return {"message": "Hello from new endpoint!"}

🧪 测试

# 테스트 실행 (pytest 설치 후)
pytest

# 커버리지와 함께 테스트
pytest --cov=app

📈 开发工具

该模板支持以下开发工具：

  • 黑色：代码格式化
  • 拉夫：打印和代码质量检查
  • pytest：测试框架
# 코드 포매팅
black app/

# 린팅
ruff check app/

# 자동 수정
ruff check app/ --fix

🐳 Docker支持

要使用Docker，请添加以下Dockerfile：

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8001

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"]

📚 参考资料

🤝 贡献

如果您有任何问题或改进，请随时为我们做出贡献！

📄 许可证

MIT许可证

相关 MCP