AI导哈

费用追踪服务器

一个基于Python和FastMCP的本地模型上下文协议(MCP)服务器，用于自然语言费用记录和Excel数据存储。

  • by andreajrubino
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 andreajrubino/expense-tracker-mcp

使用说明

费用跟踪MCP服务器

基于Python的模型上下文协议的企业级文档 （MCP）费用跟踪服务器。

⚠️ 概念验证（PoC）

这是一个基于2026年2月可用的框架和库的快速而肮脏的实现。

行为、API和集成模式可能会在FastMCP、OpenAI Codex和相关工具的未来版本中发展。 这只是出于示范目的

目录

  1. 简介
  2. 架构概述
  3. 环境设置（基于紫外线）
  4. 已安装的包
  5. 项目结构
  6. MCP服务器概述
  7. 核心功能组件
  8. Excel存储层
  9. 运行服务器
  10. MCP检验员测试
  11. VS Code中与Codex的集成
  12. 操作注意事项
  13. 未来改进

1.导言

该项目实施了一个本地 模型上下文协议（MCP）服务器 使用Python和FastMCP。

📢 教育概念证明

此存储库包含有意设计的简单演示代码 开始使用MCP服务器并了解它们的工作原理。 实施优先考虑清晰度和可接近性，而不是生产级 架构、高级模式或高度优化的设计。

服务器允许自然语言费用记录，例如：

“我昨天花了20美元买了一个蝙蝠侠形象”

服务器：

  • 解析金额
  • 检测货币
  • 提取相对或明确的日期
  • 将结果存储在Excel文件中
  • 通过MCP为AI代理公开工具（例如，VS Code中的OpenAI Codex）

该项目展示了：

  • 基于本地stdio的MCP服务器设计
  • 自然语言解析
  • 结构化数据持久性
  • 通过FastMCP进行工具注册
  • 与OpenAI Codex UI集成

Codex中关于VS Code的示例结果

2.架构概述

解决方案包括：

  • FastMCP stdio服务器
  • 自然语言解析器
  • Excel持久层（openpyxl）
  • 通过装饰器进行工具注册
  • MCP通信的本地stdio传输

传输类型：-STDIO（标准输入/输出）

数据存储：Excel文件(expenses.xlsx)

执行模型：事件驱动的工具调用

3.环境设置（基于紫外线）

环境配置使用 uv 快速依赖 管理。

初始化项目

uv init

添加所需的包

uv add fastmcp openpyxl dateparser pypandoc

这将创建：

  • 虚拟环境
  • 依赖解析
  • 文件
  • 可复制环境

4.已安装的软件包

包装用途

fastmcp MCP服务器实现 openpyxl Excel读/写操作 dateparser自然语言日期解析 pypandoc文档生成 正则表达式数量解析 pathlib文件处理 日期时间戳管理

5.项目结构

project-root/
│
├── server.py
├── expenses.xlsx
├── README.md
└── .venv/

6.MCP服务器概述

服务器初始化为：

mcp = FastMCP("expense-tracker")

工具注册使用：

@mcp.tool

服务器通过以下方式启动：

if __name__ == "__main__":
    mcp.run()

服务器使用STDIO进行通信，不得打印到stdout。

7.核心功能组件

7.1_parse_amount（原始）

使用正则表达式提取数字金额。手柄：-12.000，16-12000.16- 12000

退货：

float

7.2 _原始货币

检测：-$→ 美元-欧元→ 欧元-英镑→ GBP-关键字匹配（美元， 欧元等）

返回ISO货币代码。

7.3_parse_date_iso（原始）

使用：

dateparser.search.search_dates()

配置：-首选项_日期_来源=“过去”-相关数据库= datetime.now（）-返回_AS_TIMEZONE_AWARE=假

退货：

YYYY-MM-DD

回退：-如果未检测到日期→ today

7.4 _费用（文本）

组合：-金额-货币-日期-描述

返回结构化字典：

{
    "amount": float,
    "currency": str,
    "date_iso": str,
    "description": str
}

8.Excel存储层

如果缺少，则创建Excel文件：

expenses.xlsx

标题结构：

["Date", "Description", "Amount", "Currency", "Raw Text", "Logged At"]

附录逻辑确保：-工作簿存在-正确的工作表名称-ISO 时间戳记录

读取逻辑：-动态映射头行-避免元组索引错误- 跳过空白行

9.运行服务器

直接执行

.\.venv\Scripts\python.exe server.py

进程应保持运行（stdio服务器）。

10.使用MCP检验员进行测试

启动：

npx @modelcontextprotocol/inspector python server.py

步骤：1。打开浏览器UI 2。查看工具3。呼叫 log_expense 4.打电话 list_expenses

11.在VS Code中与Codex集成

打开Codex MCP用户界面

“连接到自定义MCP”

选择：-STDIO

配置

启动命令：

C:\Users\andre\Documents\Python\MCP\Python\Stdio Server\.venv\Scripts\python.exe

论据：

C:\Users\andre\Documents\Python\MCP\Python\Stdio Server\server.py

不需要环境变量。

保存后：-启用MCP工具-在Codex聊天中使用：

例子：

Log this expense: I spent 50 dollars on groceries yesterday

12.操作注意事项

  • 不打印到stdout
  • 使用stderr进行调试
  • 始终使用绝对python路径
  • 确保虚拟环境的一致性
  • 写入过程中保持Excel关闭
  • 考虑将文件锁定用于生产环境

13.未来的改进

  • 类别自动检测
  • 重复数据删除逻辑
  • CSV导出
  • SQLite后端
  • 多用户存储
  • 认证层
  • 云部署（HTTP MCP）
  • 使用Pydantic进行结构化验证

相关 MCP