AI导哈

本地费用追踪系统

一个基于FastMCP和SQLite的轻量级本地费用追踪系统，提供高效的AI集成和个人财务管理功能。

  • by Lnxtanx
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Lnxtanx/expense-tracker-mcp-server

使用说明

💰 本地-MCP费用追踪器

创建者：Vivek

一个功能强大且轻量级的费用跟踪系统，采用FastMCP和SQLite构建为模型上下文协议（MCP）服务器。该项目展示了使用现代Python开发实践来创建高效本地数据管理工具的方法。

🏗️ 项目概述

“本地-MCP费用追踪器”是一个既复杂又简洁的费用管理系统，它利用模型上下文协议（Model Context Protocol）实现了与AI助手及其他MCP兼容客户端的无缝集成。该系统采用Python和SQLite构建，为个人财务追踪提供了坚实的基础，同时避免了外部依赖的复杂性。

🎯 主要特点

  • 🔧 MCP 服务器架构基于FastMCP框架，实现无缝AI集成
  • 💾 本地 SQLite 数据库安全、基于文件的存储，无外部依赖
  • 📊 费用管理添加、查看和组织费用，使用类别和子类别进行分类
  • 🏷️ 灵活分类支持主要类别和详细子类别
  • 支持说明/支持备注为每一笔费用条目添加详细描述
  • ⚡ 高速性能通过索引操作优化数据库查询
  • 🔒 数据隐私所有数据均本地存储在您的机器上

🛠️ 技术栈

核心技术

  • **Python 3.10+**带有类型提示和性能优化的现代Python
  • **FastMCP（注：FastMCP可能是一个特定技术、项目或系统的名称，在中文中没有直接对应的翻译，因此保持原样）**用于AI集成的轻量级MCP服务器框架
  • SQLite3用于本地数据存储的嵌入式关系数据库
  • UV包管理器快速、可靠的Python包管理

开发工具

  • **Git（一种分布式版本控制系统）**使用全面的.gitignore进行版本控制
  • 虚拟环境使用 .venv 创建独立的 Python 环境
  • 项目配置现代 pyproject.toml 配置

📁 项目结构

expenses/
├── 📄 main.py              # Main MCP server implementation
├── 🧪 test.py              # Test suite (duplicate of main for testing)
├── 📊 expenses.db          # SQLite database file (auto-generated)
├── ⚙️ pyproject.toml       # Project configuration and dependencies
├── 📚 README.md            # This comprehensive documentation
├── 🔒 .gitignore           # Git ignore patterns
├── 🐍 .python-version      # Python version specification (3.10)
├── 🔐 uv.lock              # Dependency lock file
├── 📁 .venv/               # Virtual environment directory
├── 📁 .git/                # Git repository metadata
└── 📁 __pycache__/         # Python bytecode cache

🗄️ 数据库模式

费用表

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Unique identifier
    date TEXT NOT NULL,                     -- Expense date (YYYY-MM-DD format)
    amount REAL NOT NULL,                   -- Expense amount (decimal)
    category TEXT NOT NULL,                 -- Main category (e.g., "Food", "Transport")
    subcategory TEXT DEFAULT '',            -- Detailed subcategory (e.g., "Restaurant", "Gas")
    note TEXT DEFAULT ''                    -- Additional notes or description
);

数据库特性

  • 自动递增ID每项费用的唯一标识符
  • 日期存储基于文本的日期存储以提高灵活性
  • 十进制精度用于精确存储货币值的实数存储
  • 可选字段子类别和备注，默认值为空
  • 索引查询针对基于日期的排序和检索进行了优化

🚀 安装与设置

先决条件

  • Python 3.10 或更高版本
  • UV 包管理器（推荐）或 pip

快速入门

# Clone the repository
git clone https://github.com/Lnxtanx/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

# Create and activate virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# Install dependencies
uv sync
# or with pip
pip install fastmcp

# Run the MCP server
python main.py

数据库初始化

当服务器首次运行时，SQLite 数据库会自动创建。无需手动设置！

🔧 MCP 工具与 API

可用工具

1. add_expense

目的向数据库中添加一条新的费用记录

参数：

  • date （必填）：费用日期，格式为YYYY-MM-DD
  • amount （必填）：费用金额，以小数形式表示
  • category （必填）：主要支出类别
  • subcategory （可选）：详细子类别
  • note （可选）：附加描述

回报包含状态和新费用ID的JSON对象

示例用法：

add_expense(
    date="2025-10-09",
    amount=15.50,
    category="Food",
    subcategory="Lunch",
    note="Team lunch at downtown restaurant"
)

2. list_expenses

目的按日期（最新在前）检索所有费用

参数无

回报包含所有字段的费用对象数组

示例回复：

[
    {
        "id": 1,
        "date": "2025-10-09",
        "amount": 15.50,
        "category": "Food",
        "subcategory": "Lunch",
        "note": "Team lunch at downtown restaurant"
    }
]

💡 使用示例

类别建议

  • 食物餐厅、杂货、小吃、咖啡
  • 交通天然气，公共交通，出租车，停车
  • 娱乐电影、游戏、书籍、订阅服务
  • 公用事业电、水、网络、电话
  • 医疗保健医生、药店、保险、牙科
  • 购物服装、电子产品、家居、个人护理

与AI助手的集成

这个MCP服务器可以与支持模型上下文协议的AI助手集成，从而实现自然语言的费用追踪：

"Add a $12.50 expense for coffee this morning"
"Show me all my food expenses this month"
"Record $45 for gas yesterday"

🧪 测试

该项目包含一个测试文件（test.py) 用于测试目的，其镜像了主要实现：

# Run tests
python test.py

🔒 安全与隐私

  • 本地存储所有数据都保留在您的本地机器上
  • 无网络依赖完全离线运行
  • SQLite 安全性如需，数据库文件可以加密
  • 版本控制通过.gitignore排除敏感数据

🚀 未来改进

计划中的功能

  • [ ] 费用的日期范围筛选
  • [ ] 基于类别的费用概览
  • [ ] 月度/年度费用报告
  • [ ] 预算追踪和提醒
  • [ ] 数据导出功能（CSV，JSON）
  • [ ] 费用编辑和删除工具
  • [ ] 高级搜索和筛选
  • [ ] 数据可视化集成

潜在的集成方案

  • [ ] 银行账户同步
  • [ ] 收据图像处理
  • [ ] 多币种支持
  • [ ] 云备份选项
  • [ ] 移动伴侣应用

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

这个项目欢迎各方贡献！改进方向包括：

  • 额外的MCP工具和功能
  • 增强的数据库操作
  • 性能优化
  • 文档改进
  • 测试覆盖率扩展

如何贡献

  1. 为项目创建分支（或：fork该项目）
  2. 创建你的功能分支（git checkout -b feature/AmazingFeature)
  3. 提交您的更改（git commit -m 'Add some AmazingFeature')
  4. 推送到分支（git push origin feature/AmazingFeature)
  5. 提交一个拉取请求

开发说明

代码质量

  • 清晰易读的Python代码，具备适当的错误处理
  • 使用参数化查询的SQLite最佳实践
  • FastMCP框架集成
  • 一致的代码格式和结构

性能考量

  • 通过适当的索引实现高效的数据库查询
  • 最小的内存占用
  • 快速启动时间
  • 针对频繁的读写操作进行了优化

📄 许可证

这个项目由Vivek创建，仅供个人和教育用途。请根据您的需求自由修改和扩展。

📞 联系方式

维维克 - 创建者和维护者

项目链接： https://github.com/Lnxtanx/expense-tracker-mcp-server 翻译为中文是：“https://github.com/Lnxtanx/费用追踪器-MCP服务器”

🆘 支持

对于问题、疑问或贡献：

  1. 检查数据库文件的权限
  2. 验证Python版本兼容性（3.10及以上）
  3. 确保虚拟环境已激活
  4. 检查与 SQLite 相关的错误日志

由Vivek用心打造❤️ | 通过现代Python开发实现高效的费用追踪

相关 MCP