学习 FastMCP - MCP 服务器示例

一个学习项目，演示如何使用 FastMCP 构建 Model Context Protocol (MCP) 服务器；FastMCP 是一个用于创建与 MCP 兼容的工具和资源的 Python 框架。

关于本项目

本仓库包含两个完整的 MCP 服务器实现：

• Demo Server - 学习 FastMCP 基础知识的简单示例

• Expense Tracker - 一个功能完备的真实应用

非常适合了解如何构建可供 Claude、其他 AI 模型或自定义应用程序使用的 MCP 服务器。

Related MCP server: expense-tracker-mcp-server

📋 服务器 1：Demo Server (main.py)

一个带有基础工具的入门级 MCP 服务器。

工具

roll_dice(n_dice: int) -> list[int]

掷 n 个六面骰子并返回结果。

roll_dice(3) → [4, 2, 6]

add_numbers(a: float, b: float) -> float

将两个数字相加并返回总和。

add_numbers(5, 3) → 8

运行 Demo Server

python main.py

💰 服务器 2：Expense Tracker (test.py)

一个功能全面的费用管理 MCP 服务器，具备数据库持久化、分类和高级筛选功能。

功能特点

• 使用 SQLite 数据库进行持久化存储

• 层级分类系统（主类别 + 子类别）

• 日期范围筛选

• 按类别汇总费用

• CRUD 操作（创建、读取、更新、删除）

• 类别合并/重命名

数据结构

每条费用记录包含：

• id - 唯一标识符（自动递增）

• date - 费用日期（字符串格式）

• amount - 费用金额（数值）

• category - 主类别（来自 categories.json）

• subcategory - 可选子类别，用于详细跟踪

• note - 可选的描述/备注

可用类别

Expense Tracker 支持 12 个主类别，每个主类别下包含多个子类别：

• 食品 - 杂货、外出就餐、咖啡等

• 交通 - 燃油、公共交通、出租车/网约车、停车费、过路费

• 住房 - 房租、维护、房产税、维修、家具布置

• 公用事业 - 电费、水费、燃气费、网络、手机、电视

• 健康 - 药品、医生问诊、诊断检查、健身

• 教育 - 书籍、课程、在线订阅、考试费用

• 家庭与子女 - 学费、日托、玩具、活动

• 娱乐 - 电影、流媒体订阅、游戏、外出游玩

• 购物 - 服装、鞋类、电子产品、家电、家居装饰

• 订阅 - SaaS 工具、云/AI、音乐、存储、新闻通讯

• 个人护理 - 美容院、美容、化妆品、卫生用品

• 礼品与捐赠 - 个人礼物、慈善捐赠、节日礼品

• 金融与费用 - 银行手续费、投资费用等

工具

add_expense(date: str, amount: int, category: str, subcategory: str = "", note: str = "")

向数据库添加新的费用记录。

{
  "date": "2026-08-20",
  "amount": 45,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch with friends"
}

返回：{"status": "ok", "id": 1}

list_expenses(start_date: str, end_date: str)

列出指定日期范围内（含起始和结束日期，格式为 YYYY-MM-DD）的所有费用。

list_expenses("2026-08-01", "2026-08-31")

返回包含所有字段的费用记录数组。

summarize(start_date: str, end_date: str, category: str = None)

获取日期范围内按类别统计的总支出金额。可选地按特定类别进行筛选。

summarize("2026-08-01", "2026-08-31")
summarize("2026-08-01", "2026-08-31", "food")

返回：

[
  {"category": "food", "total_amount": 150},
  {"category": "transport", "total_amount": 50}
]

update_expense(id: int, date: str = None, amount: float = None, category: str = None, subcategory: str = None, note: str = None)

更新现有费用的指定字段。仅修改提供的字段。

update_expense(1, amount=50, note="Updated note")

返回：{"status": "ok", "id": 1, "updated_fields": {...}}

delete_expense(id: int)

按 id 删除费用记录。

delete_expense(1)

返回：{"status": "ok", "deleted_id": 1}

merge_categories(old_categories: list[str], new_category: str)

将一个或多个类别标签重命名或合并为单个新类别。适用于整合费用类别。

merge_categories(["food", "dining"], "meals")

返回：{"status": "ok", "rows_updated": 15, "new_category": "meals"}

资源

expense://categories

以 JSON 格式返回类别结构。此资源每次都会重新读取，因此您可以编辑 categories.json 而无需重启服务器。

运行 Expense Tracker

python test.py

数据库：在同一目录中创建 expenses.db 以进行持久化存储。

安装与设置

前提条件

• Python 3.14+

• FastMCP 3.4.7+

安装依赖

pip install fastmcp>=3.4.7

或使用项目的 pyproject.toml：

pip install -e .

项目结构

learn-fastmcp/
├── main.py              # Demo server (roll_dice, add_numbers)
├── test.py              # Expense Tracker server (full MCP implementation)
├── categories.json      # Category definitions for expense tracker
├── expenses.db          # SQLite database (auto-created by test.py)
├── pyproject.toml       # Project configuration
└── README.md            # This file

学习路径

1. 从 main.py 开始，了解基础知识：

   • 如何创建 FastMCP 实例

   • 如何使用 @mcp.tool 装饰器定义简单的工具

   • 如何使用 mcp.run() 运行服务器

2. 进阶到 test.py，学习高级模式：

   • SQLite 数据库集成

   • 文件 I/O 和资源管理

   • 复杂的工具逻辑（CRUD 操作）

   • 使用 @mcp.resource 装饰器定义资源

   • 可选参数和条件参数

   • 错误处理与验证

FastMCP 核心概念

工具

使用 @mcp.tool() 装饰的函数，可由 MCP 客户端调用。每个工具包含：

• 带类型提示的输入参数

• 描述功能的文档字符串

• 返回值

资源

可通过 URI 访问的静态或动态内容。使用 @mcp.resource() 定义：

• 由唯一 URI 标识（例如 expense://categories）

• 可选地指定 MIME 类型

• 可以从文件读取或动态计算

服务器生命周期

mcp = FastMCP("ServerName")  # Create instance

@mcp.tool()                  # Define tools
def my_tool(): ...

if __name__ == "__main__":
    mcp.run()               # Start the server

后续步骤

• 修改 Demo Server 以添加新工具

• 扩展 Expense Tracker，加入新功能（例如预算、周期性费用）

• 为您感兴趣的领域创建自己的 MCP 服务器

• 使用 MCP 协议将您的 MCP 服务器连接到 Claude

参考资料

• MCP 文档

• FastMCP GitHub

• Python typing 模块文档

祝学习愉快！🚀