Personal Expense Tracker MCP

项目简介

Personal Expense Tracker MCP 是一个用于追踪个人支出的简单本地 MCP 服务器。

它把支出数据存储在本地的 CSV 文件中。

该服务器为 MCP 客户端提供五个功能明确的工具：

• 添加一项新支出

• 列出已保存的支出

• 生成支出汇总

• 更新已有支出

• 删除已有支出

本项目设计得简单且易于在本地运行。

不需要银行账户或外部 API。

Related MCP server: expense-mcp

环境要求

开始之前，请确保你已安装以下环境：

• Node.js 20 或更新版本

• npm

• Git

检查 Node.js

node --version

检查 npm

npm --version

检查 Git

git --version

安装

1 克隆仓库

git clone https://github.com/MohammadYousef-001/Personal-Expenses-Tracker.git

2 进入项目目录

cd Personal-Expenses-Tracker

3 安装依赖包

npm install

等待 npm 完成依赖包的安装。

数据文件

支出数据存储在本地文件中：

data/expenses.csv

CSV 文件使用以下列：

id,amount,category,date,description

不要更改这些列的名称。

运行 MCP 服务器

运行以下命令启动服务器：

npm run dev

服务器的 MCP 通信使用标准输入和标准输出。

它是一个本地服务器，不需要 Web 端口。

运行 MCP Inspector

MCP Inspector 是手动测试这些工具的最简单方式。

运行：

npm run inspect

浏览器窗口会打开 MCP Inspector。

如果没有自动打开，请使用终端中显示的 URL。

在 Inspector 中：

1. 连接到本地服务器

2. 打开 Tools 部分

3. 选择一个工具

4. 输入输入内容

5. 点击 Execute Tool

6. 检查结果

可用工具

工具 1 add_expense

使用 add_expense 保存一条新支出

输入参数

amount

支出的金额

必须是一个正数

category

支出类别

例如

groceries
transport
bills
shopping

类别会小写保存，这样类别名称就能保持一致

date

支出的日期

必须使用

YYYY-MM-DD

例如

2026-08-12

日期还必须是真实存在的日历日期

下面的示例是无效的

2026-99-99

description

可选填的支出说明

示例

{
  "amount": 25,
  "category": "groceries",
  "date": "2026-08-12",
  "description": "milk and bread"
}

一个成功的请求会把支出添加到

data/expenses.csv

工具 2 list_expenses

使用 list_expenses 查看已保存的支出

不添加过滤条件时

{}

按类别过滤

{
  "category": "groceries"
}

按月份过滤

{
  "month": "2026-08"
}

同时使用两个过滤条件

{
  "month": "2026-08",
  "category": "groceries"
}

月份必须使用

YYYY-MM

月份必须在 01 和 12 之间

以下写法是无效的

2026-99

工具 3 get_spending_summary

使用 get_spending_summary 查看支出的汇总信息

示例

{
  "month": "2026-08"
}

结果可以包括

• 所选月份

• 支出总金额

• 支出笔数

• 每个类别的支出合计

结果示例

month: 2026-08
total amount: 150
expense count: 4

category totals:
groceries: 80
transport: 30
bills: 40

实际的值取决于 data/expenses.csv 中的数据

常见用途示例

添加一笔支出

I spent 25 on groceries today

以下提示词可以用来创建这种请求：

add_expense

查找支出

show my grocery expenses for this month

以下提示词可以用来创建这种请求：

list_expenses

检查支出情况

how much did I spend this month

以下提示词可以用来创建这种请求：

get_spending_summary

输入校验

本项目会在使用工具之前对工具输入进行校验

无效输入示例：

• 负数金额

• 金额为零

• 日期格式错误

• 日期不存在

• 无效月份

• 类别过长

• 描述过长

无效输入会在保存之前被拒绝

测试 Schema

运行

npm run check:schema

如果一切正常，应该会显示

All expense schemas are valid.

故障排查

问题 1 packages 缺失

如果出现提示找不到某个包或模块的错误信息，运行

npm install

然后再去操作

npm run dev

问题 2 MCP Inspector 无法启动

先确认依赖包已经安装

npm install

再运行

npm run inspect

如果旧 Inspector 进程仍在运行，请按 Ctrl+C（macOS / Linux）或 Ctrl+C（Windows）

Ctrl + C

停掉旧进程后再操作 Inspector

问题 3 TypeScript 或 schema 错误

运行

npm run check:schema

如果一切正确，你应该可以看到

All expense schemas are valid.

如果出现错误，请一次性终端中显示的文件名和行号

修复错误后再启动 Inspector

问题 4 无效日期

日期必须符合

YYYY-MM-DD

有效示例

2026-08-12

无效示例

2026-99-99

问题 5 没有返回任何支出

检查文件

data/expenses.csv

确保在 CSV 表头下面有数据行

如果文件中只有表头，那么返回空结果是正常的

项目结构

需要注意的是

Personal-Expenses-Tracker/
│
├── data/
│   └── expenses.csv
│
├── docs/
│   ├── design.md
│   └── threat-model.md
│
├── examples/
│
├── src/
│   ├── index.ts
│   ├── schemas/
│   ├── tools/
│   └── lib/
│
├── SECURITY.md
├── package.json
└── README.md

安全

工具输入被视为不可信输入

该项目在重要操作之前会对输入进行校验

支出文件的只由本应用掌控

返回给 MCP 客户端的错误保持简短以免泄露，没有必要

更详细的错误信息会保留在本地终端方便调试

这些支出工具不需要 NTP网络请求MPTCP

更多安全主题的信息见

SECURITY.md

项目范围

这是个小型的本地个人支出追踪项目

它不包含：

• 银行账户连接

• 自动银行数据导入

• 用户登录

• 云数据库

• 图形界面应用

• 财务预测

核心目标是为本地支出记账提供一组简单 MCP

使用许可证

本项目使用 MIT 许可证

许可协议见 LICENSE