A
licenseNot graded
qualityD
maintenanceA lightweight MCP server for tracking personal expenses, income, and budget summaries using SQLite.
4
Martin Birgmeier
expense-tracker
by ansh-rohilla
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@expense-trackerSummarize my food expenses for July 2026"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Expense Tracker MCP Server
A lightweight Model Context Protocol (MCP) server for recording, browsing, and summarizing expenses. It stores data locally in SQLite and exposes a curated category list as an MCP resource, so an MCP client can help keep spending records organized without relying on a hosted service.
Features
Add expenses with a date, amount, category, optional subcategory, and note
List expenses within an inclusive date range
Summarize spending by category, with an optional category filter
Read the available categories and subcategories from
expense://categoriesPersist everything locally in
expenses.db
Related MCP server: Expense Tracker MCP
Requirements
Python 3.13 or newer
uv(recommended)
Install
Clone the repository and install the project dependencies:
git clone https://github.com/ansh-rohilla/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server
uv syncRun the server
Start the server with:
uv run python main.pyThe SQLite database is created automatically at expenses.db in the project root on first run.
Configure an MCP client
Add the following server entry to your MCP client's configuration. Replace /absolute/path/to with the path where you cloned this repository.
{
"mcpServers": {
"expense-tracker": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/expense-tracker-mcp-server",
"run",
"python",
"main.py"
]
}
}
}For example, in Claude Desktop this entry belongs in claude_desktop_config.json. Restart the client after saving the configuration.
Available tools
add_expense
Adds an expense to the local database.
Parameter | Required | Description |
| Yes | Date of the expense, preferably |
| Yes | Expense amount as a number |
| Yes | A top-level category such as |
| No | A more specific category, such as |
| No | Any useful context about the expense |
Example request:
Add an expense of 450 on 2026-08-02 for groceries under food. Note: weekly vegetables.list_expenses
Returns expenses whose dates fall within the inclusive range.
Parameter | Required | Description |
| Yes | Beginning of the date range ( |
| Yes | End of the date range ( |
summarize
Returns total spending grouped by category for an inclusive date range.
Parameter | Required | Description |
| Yes | Beginning of the date range ( |
| Yes | End of the date range ( |
| No | Limit the summary to one category |
Categories resource
The server provides expense://categories as JSON. It reads from categories.json, which you can customize to match your own budgeting system. Common top-level categories include food, transport, housing, utilities, health, education, entertainment, shopping, travel, investments, and more.
Data and privacy
Expenses remain on your machine in the local SQLite database. Back up expenses.db if you want to retain your records when moving or reinstalling the project. Because the database can contain personal financial information, avoid committing a populated copy to a public repository.
Project layout
.
├── main.py # FastMCP server and expense tools
├── categories.json # Available categories and subcategories
├── expenses.db # Local SQLite database (created automatically)
├── pyproject.toml # Project metadata and dependencies
└── uv.lock # Locked dependency versionsLicense
No license has been specified yet. Add a license file before distributing or reusing this project publicly.
Available Tools
3 toolsadd_expenseC
Add a new expense entry to the database.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| note | No | ||
| amount | Yes | ||
| category | Yes | ||
| subcategory | No |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states that an entry is added, but does not disclose validation behavior, duplicate handling, side effects, required-field enforcement, or what happens after a successful add.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with virtually no filler. It could be considered slightly under-specified, but as far as conciseness and structure go, it is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter create operation with no annotations, no output schema, and no schema descriptions, this is not a complete definition. The description misses parameter details, input formats, result/error behavior, and any explicit differentiation from sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate by explaining any of the parameters. The agent must rely entirely on parameter names like date, amount, category, subcategory, and note, with no type, format, or semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Add a new expense entry to the database.' It uses a specific verb and resource, and the action is distinct from the sibling tools list_expenses and summarize, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus list_expenses or summarize outside of the obvious 'add' intent. There are no prerequisite conditions, exclusions, or alternative routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_expensesA
List expense entries within an inclusive date range.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| start_date | Yes |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It clearly identifies a read operation and the inclusive date-range boundary, but does not mention pagination, ordering, or the returned fields. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence front-loads the verb, resource, and main constraint. There is no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool, the description covers the core action and range semantics. However, the lack of an output schema and absence of return-shape or date-format guidance leaves some ambiguity for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds the key semantic that the range is inclusive, but it does not specify the expected date format or confirm how each parameter maps beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('expense entries'), and adds a clear scope (inclusive date range). This distinguishes it from siblings 'add_expense' (create) and 'summarize' (aggregate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the name and siblings, but there is no explicit statement about when to choose this over 'summarize' or how it relates to 'add_expense'. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
summarizeA
Summarize expenses by category within an inclusive date range.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | ||
| end_date | Yes | ||
| start_date | Yes |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that the date range is inclusive, which is useful, but it does not mention whether the operation is read-only, what metrics are returned, or how categories with no expenses are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no redundancy or filler. Every word contributes to the tool's core behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter summarization tool, the description gives the essential operation but leaves gaps. With no annotations and no output schema, it should say more about the return shape, optional category behavior, and what 'summarize' actually computes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for any parameter (0% coverage), so the description must compensate. It adds meaning by connecting category to grouping and start_date/end_date to an inclusive range, but it does not clarify whether category is a filter or required grouping key, nor the expected date format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('summarize') and resource ('expenses'), and adds the grouping dimension (by category) and date range scope. This clearly distinguishes it from the sibling tools add_expense and list_expenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: summarize rather than add or list expenses. However, there is no explicit guidance about when to prefer this tool over list_expenses or what scenarios it is not suited for, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- First observed
add_expense - First observed
list_expenses - First observed
summarize
TDQS
A3.5/5.0
Scored across 3 tools
Disambiguation5/5
Each tool has a clearly distinct purpose: adding, listing, and summarizing expenses. There is no overlap or ambiguity in functionality.
Naming Consistency4/5
The first two tools follow a verb_noun pattern (add_expense, list_expenses), but the third tool is just 'summarize' without a noun. This is a minor deviation from an otherwise consistent pattern.
Tool Count5/5
With 3 tools, the server is well-scoped for an expense tracker. Each tool serves a necessary and distinct function without unnecessary bloat.
Completeness3/5
The server provides create (add), read (list), and aggregate (summarize) functionality, but lacks update and delete operations. This is a notable gap for a complete expense tracking lifecycle.
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
MCP server for Pinchwork - an agent-to-agent task marketplace with credits-based economy
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceMCP server for tracking expenses with local SQLite storage. Provides tools to add, list, and summarize expenses by category.-
- FlicenseNot gradedqualityBmaintenanceA simple MCP server for tracking expenses in a local SQLite database, enabling add, read, update, delete, and summarization of expenses with predefined categories.-
- FlicenseNot gradedqualityCmaintenanceA lightweight local MCP server for tracking personal or small-team expenses. It lets you add expense entries, list transactions within a date range, and generate simple summaries by category — all backed by a local SQLite database.-