使用说明

现金支出跟踪器MCP服务器

MCP（模型上下文协议）服务器，提供对Cashew费用跟踪器SQLite数据库的访问。此服务器将表模式作为资源公开，提供运行只读SQL查询的工具，并包括常见数据分析任务的提示。

特性

数据库架构资源：访问完整的表架构和结构信息
只读SQL查询工具：对您的支出数据执行安全的SELECT查询
数据分析提示：常见费用分析任务的预构建提示
多数据库支持：在测试和生产数据库之间切换
安全第一：只允许只读操作来保护您的数据

安装

该项目使用紫外线用于依赖性管理。确保您安装了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 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检查员（开发）

使用MCP检查器测试服务器：

uv run mcp dev cashew_mcp_server.py

可用资源

服务器公开以下资源：

数据库架构资源

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

Cashew数据库中的示例表：

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

可用工具

SQL查询工具

execute_sql_query（查询：str）
- 执行只读SELECT查询
- 返回包含列、行和执行元数据的结果
- 安全检查防止危险操作
get_table_sample（表名：str，限制：int=10）
- 从任何表中获取示例行
- 有助于探索数据结构
- 最多100行
get_table_count（表名：str）
- 获取任何表的总行数
- 数据量快速概览

可用提示

数据分析提示

分析_支出_模式
- 综合支出模式分析
- 类别细分和趋势
- 时间支出模式
- 预算执行情况分析
预算分析
- 预算绩效评价
- 预算与实际支出
- 预算调整建议
- 未来预测
收入_支出
- 收入和支出比较
- 现金流量分析
- 财务健康指标
- 趋势分析和预测
正常检测费用
- 检测异常支出模式
- 识别潜在的重复交易
- 查找支出异常和异常值
- 预算违规检测

查询示例

以下是一些示例SQL查询，您可以使用 execute_sql_query 工具：

基础数据探索

-- 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数据库包含以下主要表：

钱包：用于组织财务的不同账户/钱包
分类：具有层次结构的收入和支出类别
交易：所有具有金额、日期和分类的财务交易
预算：带有时间段和金额的预算定义
目标：财务目标和指标
类别_预算_限额：特定类别的预算限制

每个表都包括审计字段，如 date_created 和 date_time_modified 用于跟踪变化。

安全功能

只读访问：只允许SELECT查询
查询验证：危险的SQL关键字被阻止
输入消毒：所有输入在执行前都经过验证
错误处理：优雅的错误处理，信息丰富

发展

要贡献或修改服务器，请执行以下操作：

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

故障排除

常见问题

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

调试模式

使用调试输出运行服务器：

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

服务器将输出：

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

许可证

该项目根据MIT许可证获得许可。