From Scratch

从零开始搭建MCP服务器

  

一个全面的学习资源库，用于从零开始构建模型上下文协议（MCP）服务器。通过8个循序渐进的示例，掌握MCP开发技能，从基础的本地服务器到高级的集成云应用，实现实际的费用跟踪功能。

🚀 快速入门

# Clone and setup
git clone 
cd MCP-Server-From-Scratch
uv sync

# Run your first MCP server
uv run fastmcp run "1.Basic_Local_Server.py"

# Debug with MCP Inspector
uv run fastmcp dev "2.Expense_Tracker_Local_Server.py"

📚 学习路径

这个仓库遵循一种 渐进式的8步学习方法：

第一阶段：基础

• 1. Basic_Local_Server.py（基本本地服务器文件） - 简单的本地MCP服务器，配备基本工具
• 2. 本地服务器费用追踪器.py - 配备SQLite数据库的本地服务器
• 3. Basic_Remote_Server.py（基础远程服务器.py） - 基于HTTP的远程服务器

第二阶段：实际应用

• 4. 费用追踪器远程服务器.py - 具备高级功能的异步远程服务器
• 5. 在Claude-Desktop.py中使用自定义服务器（免费版） - Claude Desktop 集成

第三阶段：高级图案

• 6. 客户端_使用配置文件.py - 带配置的MCP客户端
• 7. 构建_费用追踪器_SSE服务器.py - 服务器发送事件传输
• 8. 构建_费用追踪器_SSE客户端.py - SSE客户端实现

🛠️ 你将学到的内容

核心MCP概念

• 本地服务器与远程服务器 - STDIO 与 HTTP 传输协议
• 工具与资源 - 构建交互式MCP（多渠道参与/管理控制平台）功能
• 异步操作 - 现代Python中的async/await模式
• 数据库集成 - 使用 aiosqlite 的 SQLite 进行异步操作

高级功能

• 服务器发送事件（SSE） - 实时通信模式
• 云集成 - FastMCP 云代理连接
• Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”，但为保持原名特色，直译“克劳德桌面应用”或“克劳德桌面软件”亦可） - 自定义服务器集成
• 客户开发 - 构建具有内存和对话功能的MCP客户端

现实世界技能

• 费用追踪系统 - 完整的CRUD应用程序
• 品类管理 - 基于JSON的配置系统
• 错误处理 - 准备就绪的异常管理（或：可投入生产的异常处理）
• 配置管理 - 灵活的服务器配置

📁 仓库结构

MCP-Server-From-Scratch/
├── 📄 1.Basic_Local_Server.py              # Basic MCP server with dice & math tools
├── 📄 2.Expense_Tracker_Local_Server.py     # Local expense tracker with SQLite
├── 📄 3.Basic_Remote_Server.py             # HTTP remote server with resources
├── 📄 4.Expense_Tracker_Remote_Server.py  # Async remote expense tracker
├── 📄 5.Use_Custom_Server_Free_in_Claude-Desktop.py  # Claude Desktop integration
├── 📄 6.Client_Using_Config_File.py        # MCP client with Groq LLM
├── 📄 7.Build_Expense_Tracker_SSE_Server.py  # SSE transport server
├── 📄 8.Build_Expense_Tracker_SSE_Client.py  # SSE client implementation
├── 📁 config/
│   └── expense_tracker.json                # MCP client configuration
├── 📄 categories.json                      # Expense categories configuration
├── 📄 expense.db                          # SQLite database (auto-generated)
├── 📄 pyproject.toml                      # Project dependencies
└── 📄 README.md                           # This documentation

🚀 开发工作流程

运行MCP服务器

# Local server (STDIO transport)
uv run fastmcp run "1.Basic_Local_Server.py"

# Remote server (HTTP transport)
uv run fastmcp run "3.Basic_Remote_Server.py"

# Debug with MCP Inspector
uv run fastmcp dev "2.Expense_Tracker_Local_Server.py"

在Claude Desktop上安装

# Install custom server in Claude Desktop
uv run fastmcp install claude-desktop "5.Use_Custom_Server_Free_in_Claude-Desktop.py"

# Restart Claude Desktop to load the server

运行SSE服务器-客户端

# Terminal 1: Start SSE server
uv run "7.Build_Expense_Tracker_SSE_Server.py"

# Terminal 2: Run SSE client
uv run "8.Build_Expense_Tracker_SSE_Client.py"

💡 主要特点

支出追踪应用程序

• 完成CRUD操作 - 添加、列出和汇总费用
• 日期范围筛选 - 按日期范围查询费用
• 品类管理 - 分层费用类别
• 异步数据库操作 - 高性能的SQLite，结合aiosqlite使用
• 错误处理 - 强大的异常管理

传输协议

• STDIO（标准输入输出） - 本地通信（Claude Desktop）
• HTTP（超文本传输协议） - 远程服务器访问
• 上海证券交易所 - 实时服务器发送事件

云集成

• FastMCP Cloud（可译为“FastMCP云”） - 将服务器部署到云端
• 代理连接 - 连接到远程MCP服务器
• Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”） - 与Claude无缝集成

🛠️ 技术

• FastMCP - 现代Python MCP框架
• SQLite - 使用aiosqlite的嵌入式数据库
• 服务器发送事件 - 实时通信
• Claude Desktop（可译为“Claude桌面版”或保持原样，具体取决于上下文是否需要更具体的翻译） - 人工智能助手集成
• 紫外线 - 快速的Python包管理器

📖 使用示例

基本服务器工具

# Dice rolling
roll_dice(n_dice=3)  # Returns: [4, 2, 6]

# Math operations
add(15.5, 4.3)  # Returns: 19.8

费用追踪

# Add expense
add_expense(
    date="2025-01-15",
    amount=25.50,
    category="Food & Dining",
    subcategory="groceries",
    note="Weekly grocery shopping"
)

# List expenses
list_expenses("2025-01-01", "2025-01-31")

# Summarize by category
summarize("2025-01-01", "2025-01-31", category="Food & Dining")

🔧 前提条件

• Python 3.8及以上版本 - 支持异步的现代Python
• 紫外线 - 快速的Python包管理器
• 基本的Python知识 - 函数、类、async/await
• 可选用于集成测试的Claude Desktop

🤝 贡献（或“参与贡献”）

我们欢迎投稿！请随时：

• 🐛 这个表情符号通常代表“虫子”或“小虫子”，在中文里可以直接翻译为“虫子”或“小虫子”。不过，具体翻译可能根据上下文有所不同。 报告错误 - 帮助我们改进示例
• 💡 灯泡图标（常用于表示创意、灵感或想法） 建议功能 - 提出新的学习示例
• 📝 完善文档 - 让学习路径更清晰
• 🔧 修理工具或螺丝刀的象征（注：在实际中文语境中，这个符号通常不直接翻译，而是根据上下文理解为“修理”、“工具”或“螺丝刀”等含义） 提交拉取请求 - 添加你自己的MCP（多上下文处理器/管理组件等，具体含义根据上下文确定）实现

📄 许可证

这个项目采用以下许可证授权： 麻省理工学院许可证 - 详见LICENSE文件。

______________________________________________________________________

🎯 准备好掌握MCP开发了吗？ 从……开始 1.Basic_Local_Server.py 并完成全部8个示例，成为MCP专家！

📚 了解更多： FastMCP 文档 | MCP规范