Exp Tracker Local MCP

实验追踪器本地MCP（或：本地多用户客户端程序实验追踪器）

一个模型上下文协议（MCP）服务器，它使用SQLite记录个人支出，并提供FastMCP工具用于添加、列出、更新、删除和分析这些支出，包括预算工具和CSV导出功能。请按照以下步骤重新创建项目并在本地运行服务器。

先决条件

• macOS、Linux 或 Windows 系统，需安装 Python 3.12 或更高版本
• 紫外线 包管理器（推荐）
• Git 和一个代码编辑器（本教程中使用的是 VS Code）

逐步设置

1. 安装 uv

   curl -LsSf https://astral.sh/uv/install.sh | sh

1. 创建或克隆项目文件夹

   git clone https://github.com//expense-tracker-mcp-server.git
   cd expense-tracker-mcp-server

> 从零开始构建？创建一个新文件夹（例如 fastmcp-demo-server并在其中执行剩余的步骤。

1. 在 VS Code 中打开文件夹

   code .

1. 在VS Code中打开终端 （向上箭头） on macOS / Ctrl （在Windows或Linux上）。

1. 初始化uv环境

- 对于一个新文件夹： uv init . - 对于这个仓库： uv sync

1. 添加FastMCP（仅在您运行过时需要） uv init)

   uv add fastmcp

1. 验证FastMCP是否可用

   uv run fastmcp --version

1. 审查服务器代码

- main.py 定义了FastMCP服务器、SQLite架构以及MCP工具。 - categories.json 通过（某种方式）展示费用类别 expense://categories 资源。

运行和测试

• 带自动重载的开发模式

  uv run fastmcp dev main.py

• 常规跑步

  uv run fastmcp run main.py

• 直接运行Python

  uv run main.py

MCP 检测器

1. 安装 MCP 检测器。
2. 配置连接：

- 运输方式： STDIO - 命令： uv - 参数： run /absolute/path/to/main.py --no-banner - 工作目录：仓库根目录

1. 点击 连接 并以交互方式调用工具。

Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文判断是否需要具体化为某个平台或设备的桌面版）

添加服务器，以便Claude可以调用它：

uv run fastmcp install claude-desktop main.py

这个命令将服务器定义注入到 claude_desktop_config.json之后重新启动 Claude 桌面版。

可用工具

• add_expense(date, amount, category, subcategory="", note="")
• list_expenses(start_date, end_date)
• update_expense(id, date=None, amount=None, category=None, subcategory=None, note=None)
• delete_expense(id)
• summarize(start_date, end_date, category=None)
• get_statistics(start_date, end_date, category=None) – 返回计数、总计、最小值/最大值和平均值。
• get_spending_trends(start_date, end_date, group_by="month", category=None) – 显示按天/周/月/年分组的总支出。
• export_to_csv(start_date, end_date, file_path) – 将筛选后的费用写入CSV文件。
• set_budget(category, amount, start_date, end_date) – 为特定时期创建或更新类别预算。
• check_budget_status(category, start_date, end_date) – 比较实际支出与存储的预算。
• 资源 expense://categories 返回JSON数据 categories.json。

项目文件

main.py          # FastMCP server implementation
categories.json  # Expense categories served as an MCP resource
expenses.db      # SQLite database (created on first run) with expenses and budgets tables
pyproject.toml   # uv project metadata and dependencies
uv.lock          # Locked dependency versions
README.md        # This guide

数据库模式

CREATE TABLE expenses(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT ''
);

CREATE TABLE budgets(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category TEXT NOT NULL,
    amount REAL NOT NULL,
    start_date TEXT NOT NULL,
    end_date TEXT NOT NULL,
    UNIQUE(category, start_date, end_date)
);

下一步行动

• 定制化 categories.json 使用你自己的预算分类体系。
• 添加新工具（CSV导入、报告生成等）至 main.py 按需使用。
• 将服务器与额外的MCP兼容客户端或工作流进行集成。