现金支出跟踪器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.sqliteMCP客户端集成
克劳德桌面
将服务器配置添加到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许可证获得许可。