关键词

个人财务支出跟踪自动分类财务分析REST API

项目简介

Expense Tracker API是一个全面的个人支出管理系统，旨在帮助用户高效地记录、分类和分析日常开销。它提供强大的RESTful API接口，支持基于规则的自动分类，并可集成外部工具（如n8n）实现邮件自动解析。更重要的是，它集成了Model Context Protocol (MCP) 服务器功能，允许大型语言模型（LLM）客户端以标准化的方式访问财务数据并调用相关功能，从而实现AI驱动的财务洞察和管理。

主要功能点

  • 支出管理: 全面记录、查看、修改和删除各项个人支出。
  • 自动分类: 根据用户自定义的商户匹配规则，自动为新添加的支出进行智能分类。
  • 类别与规则管理: 灵活地创建、编辑和删除支出类别，以及管理用于自动分类的商户匹配规则（支持模糊匹配和正则表达式）。
  • 财务分析: 提供详细的支出摘要、类别支出明细、平均消费以及按支付方式（如信用卡、借记卡）划分的账单周期分析。
  • 电子邮件集成: 通过与n8n等自动化平台的集成，能够自动解析银行或商户的邮件通知，提取支出信息并自动创建记录。
  • MCP服务器接口: 提供标准化的MCP接口，允许LLM客户端直接获取支出数据（资源）、创建商户规则（工具），实现AI辅助的财务规划和分析。
  • API密钥认证: 所有API接口（文档页除外）均通过API密钥进行安全认证。

安装步骤

1. 克隆仓库

首先，将项目仓库克隆到本地：

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

2. 使用Docker (推荐，快速启动)

这是最简单快捷的启动方式，适用于本地开发环境。

  • 前置条件: 确保您的系统已安装Docker和Docker Compose。
  • 启动命令: 
    chmod +x docker-dev.sh # 首次运行需要赋予执行权限
./docker-dev.sh start
  • 访问: API服务器将在 'http://localhost:8000' 运行。
    • API文档: 'http://localhost:8000/docs'
    • 健康检查: 'http://localhost:8000/health'

3. 本地Python安装 (需要手动配置PostgreSQL)

  • 前置条件:
    • Python 3.8+
    • 一个运行中的PostgreSQL数据库实例。
  • 安装依赖: 
    pip install -r requirements.txt
  • 配置环境变量: 复制示例配置文件，并编辑 '.env' 文件，填入您的PostgreSQL数据库连接信息和API密钥。 
    cp .env.example .env
# 编辑 .env 文件，设置 DATABASE_POSTGRES_URL 和 API_KEY
  • 初始化数据库: 
    python app/init_db.py
  • 启动API服务器: 
    python app/main.py
    API服务器将在 'http://localhost:8000' 运行。

服务器配置 (用于MCP客户端)

您的MCP客户端（例如LM Studio）可以通过以下配置连接到此Expense Tracker MCP服务器。此配置假定MCP客户端能够直接启动一个Python进程（例如通过Stdio传输），并设置所需的API密钥。

{
  "mcpServers": {
    "expense-tracker": {
      "command": ["python", "app/main.py"],
      "args": [],
      "headers": {
        "x-api-key": "your-secret-api-key"
      }
    }
  }
}

请注意:

  • 'command': '["python", "app/main.py"]' 指示MCP客户端启动位于仓库根目录下的 'app/main.py' 文件作为一个Python进程。请确保MCP客户端的当前工作目录是仓库的根目录，或者调整为 '["python", "/path/to/your/expense-tracker/app/main.py"]'。
  • 'args': 此服务器在作为MCP服务器运行时通常不需要额外的命令行参数，因此此处为空数组。
  • 'headers': '{"x-api-key": "your-secret-api-key"}' 用于身份验证。请将 'your-secret-api-key' 替换为你在 '.env' 文件或 'API_KEY' 环境变量中设置的实际API密钥。
  • 此MCP服务器通过FastAPI框架提供服务，并暴露以下核心功能供LLM客户端调用：
    • 'get_expenses': 获取支出记录资源。
    • 'get_categories': 获取支出类别资源。
    • 'create_merchant_rule': 创建商户匹配规则的工具。
    • 'get_merchant_rules': 获取商户匹配规则资源。

基本使用方法

  1. 设置API密钥: 确保在 '.env' 文件或 'docker-compose.yml' 中设置了 'API_KEY' 环境变量。所有需要认证的API请求都必须在请求头中包含 'x-api-key: your-api-key'。

  2. 通过REST API进行操作: 您可以使用任何HTTP客户端（如'curl'、Postman、Insomnia）与FastAPI后端交互。

    • 创建类别: 
      curl -X POST "http://localhost:8000/categories/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"name": "Groceries", "description": "Food shopping", "color": "#FF6B6B"}'
    • 添加支出: 
      curl -X POST "http://localhost:8000/expenses/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "amount": 45.67,
    "merchant": "Walmart Supercenter",
    "description": "Weekly groceries",
    "transaction_date": "2024-01-15T10:30:00"
  }'

  3. 通过MCP客户端与LLM交互: 配置好您的MCP客户端（如LM Studio）后，LLM可以利用上述MCP接口进行智能交互。例如：

    • LLM可以请求获取您的最新支出记录，进行分析并给出消费建议。
    • LLM可以识别未分类的支出，并提示您创建新的商户规则。
    • LLM可以帮助您总结特定时间段的支出情况，或者根据支付方式进行预算分析。

信息

分类

生产力应用

访问项目