Personal Expenses MCP Server
# Personal Expenses MCP Server
An [MCP](https://modelcontextprotocol.io) server for tracking a personal monthly budget — salary, per-month snapshots, and running expenses — exposed as tools an MCP client (e.g. Claude Desktop or Claude Code) can call directly in conversation.
Data is stored **in memory only**; it resets whenever the server restarts.
## Requirements
- Python >= 3.12
- [uv](https://docs.astral.sh/uv/)
## Install
```bash
uv sync
```
## Run
```bash
uv run python main.py
```
## Tools
| Tool | Description |
|---|---|
| `add_person(name, base_salary)` | Adds a new person with their initial base salary. |
| `initialize_new_month(name, month, has_salary_changed, new_salary_amount=0)` | Starts a new tracking month for a person, snapshotting their current (or updated) salary. |
| `log_expense(name, month, description, amount_in_dollars)` | Logs an expense against a person's month and returns the updated total spent / salary left. |
| `get_monthly_statement(name, month)` | Returns the full expense breakdown and remaining balance for a person's month. |
## Using with an MCP client
Add an entry to the client's MCP server config (e.g. Claude Desktop's `claude_desktop_config.json`):
```json
{
"mcpServers": {
"main": {
"command": "uv",
"args": ["run", "--frozen", "--directory", "/absolute/path/to/PersonalExpenses_MCPServer", "python", "main.py"]
}
}
}
```
TDQS
Scored across 4 tools
Each tool addresses a distinct lifecycle step: person creation, month setup, expense logging, and statement retrieval. There is no overlapping functionality between any pair of tools.
All tool names follow a consistent verb_noun pattern (add_person, initialize_new_month, log_expense, get_monthly_statement). The verbs are clear and uniformly formatted in snake_case.
Four tools is a well-scoped size for a personal expense tracker, covering the core workflow without unnecessary bloat. Each tool serves a clear purpose.
The core monthly expense cycle is covered: add person, initialize month, log expenses, view statement. Minor gaps include lack of expense edit/delete and inability to view historical statements, but these are workable for a simple expense tracker.