Cashew Expense Tracker MCP Server

Cashew 记账 MCP 服务

一个 MCP（Model Context Protocol）服务，可访问你的 Cashew 记账 SQLite 数据库。此服务将表结构作为资源公开，提供用于运行只读 SQL 查询的工具，并包含适用于常见数据分析任务的提示词。

功能

• 数据库架构资源：访问完整的表架构和结构信息
• 只读 SQL 查询工具：对你的支出数据执行安全的 SELECT 查询
• 数据分析提示词：为常见支出分析任务预先构建的提示词
• 支持多个数据库：在测试数据库和生产数据库之间切换
• 安全优先：仅允许只读操作，以保护你的数据

安装

此项目使用 uv 管理依赖。请确保已安装 uv，然后运行：

uv sync

使用方法

运行服务

使用测试数据库启动 MCP 服务：

uv run python cashew_mcp_server.py

使用你的主 Cashew 数据库：

uv run python cashew_mcp_server.py --use-main-db

使用自定义数据库路径：

uv run python cashew_mcp_server.py --db-path /path/to/your/database.sqlite

MCP 客户端集成

Claude Desktop

将服务配置添加到 Claude Desktop 的 MCP 设置文件中：

{
  "mcpServers": {
    "cashew-expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "cashew_mcp_server.py"
      ],
      "cwd": "/Users/yash/Developer/cashew-mcp",
      "env": {}
    }
  }
}

VSCode

将服务配置添加到 VSCode 工作区的 MCP 设置文件中：

{
    "servers": {
        "cashew-mcp-server": {
            "type": "stdio",
            "command": "/Users/yash/Developer/cashew-mcp/.venv/bin/python",
            "args": [
                "/Users/yash/Developer/cashew-mcp/cashew_mcp_server.py",
                "--db-path",
                "/Users/yash/Developer/cashew-mcp/db.sqlite"
            ]
        }
    }
}

MCP Inspector（开发）

使用 MCP Inspector 测试服务：

uv run mcp dev cashew_mcp_server.py

可用资源

此服务公开以下资源：

数据库架构资源

• cashew://schema - 所有表的完整数据库架构
• cashew://schema/{table_name} - 特定表的详细架构

Cashew 数据库中的示例表：

• wallets - 钱包／账户信息
• categories - 支出和收入类别
• transactions - 所有财务交易
• budgets - 预算定义和限额
• objectives - 财务目标和规划
• category_budget_limits - 特定类别的预算限额

可用工具

SQL 查询工具

1. execute_sql_query(query: str)

   • 执行只读 SELECT 查询
   • 返回包含列、行和执行元数据的结果
   • 安全检查会阻止危险操作

2. get_table_sample(table_name: str, limit: int = 10)

   • 获取任意表的示例行
   • 适用于探索数据结构
   • 最多限制为 100 行

3. get_table_count(table_name: str)

   • 获取任意表的总行数
   • 快速了解数据量

可用提示词

数据分析提示词

1. analyze_spending_patterns

   • 全面的支出模式分析
   • 类别细分和趋势
   • 时间维度的支出模式
   • 预算表现分析

2. budget_analysis

   • 预算表现评估
   • 预算与实际支出的对比
   • 预算调整建议
   • 未来预测

3. income_vs_expenses

   • 收入与支出的对比
   • 现金流分析
   • 财务健康指标
   • 趋势分析和预测

4. expense_anomaly_detection

   • 检测异常支出模式
   • 找出可能重复的交易
   • 发现支出异常和离群值
   • 检测预算违规

示例查询

以下是一些可使用 execute_sql_query 工具运行的 SQL 查询示例：

基本数据探索

-- Get recent transactions
SELECT name, amount, date_created, income
FROM transactions
ORDER BY date_created DESC
LIMIT 10;

-- Top spending categories
SELECT c.name, SUM(t.amount) as total_spent, COUNT(*) as transaction_count
FROM transactions t
JOIN categories c ON t.category_fk = c.category_pk
WHERE t.income = 0
GROUP BY c.name
ORDER BY total_spent DESC
LIMIT 10;

-- Monthly spending summary
SELECT
  strftime('%Y-%m', date_created, 'unixepoch') as month,
  SUM(CASE WHEN income = 0 THEN amount ELSE 0 END) as expenses,
  SUM(CASE WHEN income = 1 THEN amount ELSE 0 END) as income,
  COUNT(*) as transactions
FROM transactions
GROUP BY strftime('%Y-%m', date_created, 'unixepoch')
ORDER BY month DESC;

预算分析

-- Current budget status
SELECT
  b.name as budget_name,
  b.amount as budget_amount,
  SUM(t.amount) as spent,
  (b.amount - SUM(t.amount)) as remaining,
  ROUND((SUM(t.amount) / b.amount) * 100, 2) as percent_used
FROM budgets b
LEFT JOIN transactions t ON t.date_created BETWEEN b.start_date AND b.end_date
  AND t.income = 0
WHERE b.archived = 0
GROUP BY b.budget_pk, b.name, b.amount;

类别分析

-- Average transaction amount by category
SELECT
  c.name as category,
  ROUND(AVG(t.amount), 2) as avg_amount,
  MIN(t.amount) as min_amount,
  MAX(t.amount) as max_amount,
  COUNT(*) as transaction_count
FROM transactions t
JOIN categories c ON t.category_fk = c.category_pk
WHERE t.income = 0
GROUP BY c.name
HAVING COUNT(*) >= 5
ORDER BY avg_amount DESC;

数据库架构

你的 Cashew 数据库包含以下主要表：

• wallets：用于整理财务信息的不同账户／钱包
• categories：具有层级结构的收入和支出类别
• transactions：所有财务交易，包含金额、日期和分类信息
• budgets：包含时间段和金额的预算定义
• objectives：财务目标和指标
• category_budget_limits：特定类别的预算限制

每个表都包含 date_created 和 date_time_modified 等审计字段，用于追踪更改。

安全功能

• 只读访问：仅允许执行 SELECT 查询
• 查询验证：禁止使用危险的 SQL 关键字
• 输入清理：执行前会验证所有输入
• 错误处理：妥善处理错误并提供详细信息

开发

如需为服务做出贡献或进行修改：

1. 安装依赖项：uv sync
2. 运行测试：uv run python -m pytest（添加测试后）
3. 格式化代码：uv run black .
4. 检查类型：uv run mypy .（添加类型提示后）

故障排除

常见问题

1. 导入错误：请使用 uv run，以正确激活虚拟环境
2. 未找到数据库：检查数据库路径，并确保文件存在
3. 权限错误：确保 SQLite 数据库文件可读

调试模式

运行服务并输出调试信息：

uv run python cashew_mcp_server.py --db-path test.sqlite

服务将输出：

• 使用的数据库路径
• 找到的可用表
• 连接状态

许可证

本项目采用 MIT 许可证。