Skip to content
Back to search

Expense-tracker-mcp-server

A local Model Context Protocol (MCP) server for recording expenses, reviewing spending, and managing monthly category budgets. It uses SQLite for storage and FastMCP for the HTTP transport.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/itsinaam--expense-tracker-mcp-server/badge.svg)](/listings/itsinaam--expense-tracker-mcp-server)

HTML

<a href="/listings/itsinaam--expense-tracker-mcp-server"><img src="/api/listings/itsinaam--expense-tracker-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python main.py

The server listens on `http://127.0.0.1:8000/mcp`. Keep it bound to localhost unless you configure an authenticated, protected deployment environment; this server does not provide application-level authentication.

For VS Code, add the following server entry to `.vscode/mcp.json` while the server is running:

{
  "servers": {
    "expense-tracker": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

To select a persistent database location, set `EXPENSE_DB_PATH` before starting the server:

$env:EXPENSE_DB_PATH = "$HOME\expense-tracker\expenses.db"
python main.py

If `EXPENSE_DB_PATH` is not set, the database is stored as `expenses.db` in the operating system's temporary directory. Temporary directories may be cleared by the OS, so configure a persistent path for important data. Existing installations using the default path continue using that same database.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 81 lines
  1. # Expense Tracker MCP Server
  2. A local Model Context Protocol (MCP) server for recording expenses, reviewing spending, and managing monthly category budgets. It uses SQLite for storage and FastMCP for the HTTP transport.
  3. ## Features
  4. - Create, list, inspect, update, and delete expense records.
  5. - Filter expenses by inclusive date range and category.
  6. - Summarize expenses by category over a date range or calendar month.
  7. - Create, list, and delete monthly category budgets.
  8. - Compare budget limits with actual spending, remaining amounts, and percentage used.
  9. - Read the configured category list through the `expense:///categories` MCP resource.
  10. ## Requirements
  11. - Python 3.10 or newer
  12. - Packages in `requirements.txt`
  13. ## Setup
  14. ```powershell
  15. python -m venv .venv
  16. .\.venv\Scripts\Activate.ps1
  17. python -m pip install -r requirements.txt
  18. python main.py
  19. ```
  20. The server listens on `http://127.0.0.1:8000/mcp`. Keep it bound to localhost unless you configure an authenticated, protected deployment environment; this server does not provide application-level authentication.
  21. For VS Code, add the following server entry to `.vscode/mcp.json` while the server is running:
  22. ```json
  23. {
  24. "servers": {
  25. "expense-tracker": {
  26. "type": "http",
  27. "url": "http://127.0.0.1:8000/mcp"
  28. }
  29. }
  30. }
  31. ```
  32. To select a persistent database location, set `EXPENSE_DB_PATH` before starting the server:
  33. ```powershell
  34. $env:EXPENSE_DB_PATH = "$HOME\expense-tracker\expenses.db"
  35. python main.py
  36. ```
  37. If `EXPENSE_DB_PATH` is not set, the database is stored as `expenses.db` in the operating system's temporary directory. Temporary directories may be cleared by the OS, so configure a persistent path for important data. Existing installations using the default path continue using that same database.
  38. ## MCP tools
  39. | Tool | Purpose | Important arguments |
  40. | --- | --- | --- |
  41. | `add_expense` | Add an expense | `date` (`YYYY-MM-DD`), positive `amount`, `category`; optional `subcategory`, `note` |
  42. | `list_expenses` | List recent expenses, newest first | Optional `start_date`, `end_date`, `category`; `limit` (1-500, default 100) |
  43. | `get_expense` | Look up one expense | `expense_id` |
  44. | `update_expense` | Change one or more expense fields | `expense_id` and any of `date`, `amount`, `category`, `subcategory`, `note` |
  45. | `delete_expense` | Delete one expense | `expense_id` |
  46. | `summarize` | Group totals and counts by category | Required inclusive `start_date`, `end_date`; optional `category` |
  47. | `monthly_summary` | Group totals and counts by category for a month | `month` (`YYYY-MM`) |
  48. | `set_budget` | Create or replace a category budget | `month` (`YYYY-MM`), `category`, positive `amount` |
  49. | `list_budgets` | List budgets | Optional `month` (`YYYY-MM`) |
  50. | `delete_budget` | Remove a category budget | `month` (`YYYY-MM`), `category` |
  51. | `budget_status` | Compare budgets with recorded spending | `month` (`YYYY-MM`) |
  52. Dates are interpreted as ISO calendar dates, and date-range endpoints are inclusive. Monetary values are stored as SQLite `REAL` numbers. Categories are user-defined strings; `categories.json` provides the recommended categories and subcategories.
  53. ## Validation and errors
  54. Amounts and budgets must be finite numbers greater than zero. Dates and months must use `YYYY-MM-DD` and `YYYY-MM`; a range's start must not be after its end. Invalid input is reported as a tool error. Lookup and deletion tools report `not_found` when the requested record does not exist.
  55. ## Development
  56. Run the focused tests with:
  57. ```powershell
  58. python -m unittest discover -s tests -v
  59. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.