finance-intelligence-mcp

财务智能 MCP 服务

Finance Intelligence MCP 是一个可用于生产环境的 Model Context Protocol（MCP） 服务，可让 AI 助手（如 Claude、Cursor 等）通过自然语言安全地管理和分析个人财务。

本项目采用 MIT License 发布，并旨在通过添加更多财务工具进行扩展。

---

🔍 概述

与标准的云端个人理财应用不同，Finance Intelligence MCP 让你完全掌控所有财务数据。

• 无需账户 / 订阅：直接连接到你的私人数据库，无需依赖任何 SaaS。
• 零遥测：你的财务记录绝不会发送到外部分析 API。
• 完整的 AI 上下文：你的 AI 助手可以查询历史记录、查看预算状态、生成图表，并即时回答财务问题。

---

🛠️ 架构

   ┌────────────────────────────────┐
   │           MCP Client           │
   │  (Claude Desktop, Cursor, etc) │
   └───────────────┬────────────────┘
                   │
                   │ (STDIO Transport Protocol)
                   ▼
   ┌────────────────────────────────┐
   │  Finance Intelligence Server   │
   │           (Local)              │
   └───────────────┬────────────────┘
                   │
                   │ (Direct SQL Pool Connection)
                   ▼
   ┌────────────────────────────────┐
   │       PostgreSQL Database      │
   │ (Supabase, Local, RDS, etc)    │
   └────────────────────────────────┘

---

✨ 功能

• 支出操作：创建、查看、编辑和批量删除支出条目。
• 多级预算：为 overall 支出设置限额，为特定 category 设置阈值，也可细化至嵌套的 subcategory 目标。
• 分析细分：按类别、子类别、备注或日期汇总支出，并按周 / 月 / 年划分时间段。
• 可视化图表：提供可自动生成历史支出 Matplotlib 折线图 / 柱状图的工具。
• Excel 电子表格导出：截断较长的列表响应，并为大型数据集生成可供下载的 Excel 电子表格。
• 财务健康评分：根据 6 项个人理财核心 KPI 计算确定性的财务健康等级评分。

---

⚙️ 要求与兼容性

• 传输方式：stdio
• 支持的平台：
  • Windows
  • macOS
  • Linux
• Python 兼容性：Python 3.10、3.11 和 3.12（已测试）
• 数据库：PostgreSQL 12+（例如 Supabase、RDS 或本地 Postgres）
• 支持的客户端：
  • Claude Desktop
  • Cursor
  • 兼容所有支持 stdio 的 MCP 客户端。

---

💾 安装与设置

1. 快速设置（快捷方式）

如果已安装 uv，只需 2 行即可开始：

git clone https://github.com/Ronit-019/Finance-Intelligence-MCP.git
cd Finance-Intelligence-MCP
uv sync

2. 详细安装

步骤 A：获取 PostgreSQL 连接 URL

最简单的免费选项是 Supabase：

1. 前往 Supabase 并创建一个免费项目。
2. 前往 Project Settings（齿轮图标）> Database。
3. 在 Connection string 下选择 URI，然后复制字符串。
   • 示例：postgresql://postgres.[your-project-ref]:[your-password]@aws-0-us-east-1.pooler.supabase.com:5432/postgres
   • （将 [your-password] 替换为你的数据库密码）。

步骤 B：克隆代码库

将代码库克隆到计算机上的一个目录：

git clone https://github.com/Ronit-019/Finance-Intelligence-MCP.git
cd Finance-Intelligence-MCP

复制该目录的绝对路径（例如 C:/Users/Admin/Desktop/Finance-Intelligence-MCP）。 注意：在 JSON 配置中，路径始终使用正斜杠（/）。

步骤 C：安装依赖项

如果尚未安装 uv，请根据项目元数据进行安装：

pip install -e .

---

3. 客户端集成

Claude Desktop 设置

1. 打开 Claude 配置文件（claude_desktop_config.json）：
   • Windows：按 Win + R，粘贴 %APPDATA%\Claude\claude_desktop_config.json，然后按 Enter。
   • macOS：在 Finder 的“前往文件夹”中粘贴 ~/Library/Application Support/Claude/claude_desktop_config.json。
2. 将此条目添加到 mcpServers 中：

{
  "mcpServers": {
    "finance-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "DATABASE_URL": "REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING"
      }
    }
  }
}

3. 保存并彻底重启 Claude Desktop。

Cursor IDE 设置

1. 前往 Settings > Features > MCP。
2. 点击 + Add New MCP Server：
   • Name：Finance Intelligence
   • Type：command
   • Command：

     uv --directory "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY" run python main.py
     

3. 点击 + Add Env Var：
   • Key：DATABASE_URL
   • Value：REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING
4. 点击 Save 并刷新。

---

💬 示例提示词

配置完成后，试着与 AI 助手对话：

• “今天午餐花了 ₹250，记在餐饮类别下。”
• “显示我本月的支出明细。”
• “生成一份 5 月至 7 月所有支出的 Excel 报告。”
• “我是否超出了每月预算上限？”
• “我这周外出就餐花了多少钱？”
• “计算我的月度财务健康评分并给出反馈。”
• “生成过去 30 天的支出图表。”

---

🛠️ 可用工具

服务会向客户端注册 12 个核心工具：

工具名称	参数	描述
add_expense	date、amount、category、subcategory、note	插入一笔新的支出交易。
list_expenses	start_date、end_date	列出交易；若数量 > 50，则导出为 Excel。
expense_breakdown	start_date、end_date、group_by、breakdown、category、subcategory	汇总支出金额和笔数。
delete_expenses	expense_ids、start_date、end_date、category、subcategory	删除符合筛选条件的支出。
update_expenses	expense_ids、filter_...、date、amount、category、subcategory、note	编辑支出记录。
create_budget	budget_type、amount、period、start_date、end_date、category、subcategory、budgets	登记新的支出限额。
list_budgets	budget_type、category、subcategory、period	返回已登记的预算。
update_budgets	budget_ids、filter_...、budget_type、amount、period、start_date、end_date、category、subcategory	修改有效预算。
delete_budgets	budget_ids、start_date、end_date、budget_type、category、subcategory、period	删除目标预算限额。
compare_budget_vs_expenses	reference_date、budget_type、category、subcategory、period	比较预算与实际支出。
expense_summary	period、group_by、category、subcategory、start_date、end_date	生成 Matplotlib 折线图或柱状图。
financial_health_score	reference_month	评估 6 项个人理财关键指标。

---

💡 故障排除

1. uv: command not found

如果客户端无法找到 uv，请更新配置文件以运行标准 Python：

• 确保已在仓库内运行 pip install -e .。
• 更新配置：

"finance-intelligence": {
  "command": "python",
  "args": [
    "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY/main.py"
  ],
  "env": {
    "DATABASE_URL": "REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING"
  }
}

2. 无效的 DATABASE_URL / PostgreSQL 连接错误

• 确保已在 Supabase URI 字符串中将 [your-password] 替换为实际的数据库密码。
• 确保 URL 字符串前后没有空格，也不含特殊字符。
• 确认 Supabase 实例处于活动状态且未暂停。

3. Claude 未检测到服务

• 仔细检查 claude_desktop_config.json 中的文件夹路径是否使用正斜杠（/），即使是在 Windows 上也是如此。
• 查看 %APPDATA%\Claude\logs\mcp*.log（Windows）或 ~/Library/Logs/Claude/mcp*.log（macOS）中的日志，了解确切的启动错误。

---

📁 仓库结构

├── src/                       # Helper packages
│   ├── __init__.py
│   ├── budget.py              # Budget database operations
│   ├── analytics.py           # Breakdown aggregations & Matplotlib routines
│   └── health.py              # KPIs and financial health calculator
├── main.py                    # FastMCP Server application
├── categories.json            # Category mapping catalog
├── pyproject.toml             # Dependencies
├── LICENSE                    # MIT License file
└── README.md                  # This file

---

🤝 参与贡献

欢迎贡献代码、报告 Bug 和提出功能请求！ 提交重大更改或拉取请求前，请先创建一个 issue。

---

📄 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

---

👨‍💻 作者

Ronit Rajput

• 作品集：https://ronitportfolio-seven.vercel.app/assistant
• GitHub：https://github.com/Ronit-019
• LinkedIn：https://www.linkedin.com/in/ronit-rajput/