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 Tracker MCP Add a $45.75 lunch expense to Dining and show my balance"
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.
A local expense and income tracker backed by SQLite. The project provides a Model Context Protocol (MCP) server for AI assistants (such as Claude Desktop, Cursor, and other MCP clients) and an optional FastAPI REST server for HTTP clients.
Expenses: Add, list, edit, and delete expense records.
Income & Credits: Store income/credit entries and calculate your current balance in real time.
Categorization: Summarize spending grouped by category with optional date and category filters.
Category Catalog: Load and query category/subcategory definitions from categories.json.
Local Storage: All records are stored locally in SQLite (expenses.db), ensuring privacy.
Related MCP server: Expense Tracker MCP Server
Python: 3.13 or newer
FastMCP: High-performance MCP server implementation
SQLite: Local relational storage
FastAPI & Uvicorn: Optional REST API with OpenAPI documentation
uv: Fast Python package and dependency manager
.
|-- expense_tracker.py # Main FastMCP expense tracker server
|-- server.py # Optional FastAPI REST API server
|-- categories.json # Expense categories and subcategories catalog
|-- pyproject.toml # Project metadata and dependencies (uv)
|-- uv.lock # Locked Python dependencies
|-- expenses.db # Local runtime SQLite database (git-ignored)
`-- src/expense_tracker_mcp/ # Package entry point
`-- __init__.pyInstall uv if not already installed.
Clone or navigate to this directory and sync dependencies:
# Sync core MCP dependencies
uv sync
# (Optional) Include FastAPI REST dependencies
uv sync --extra apiThe database (expenses.db) and its tables are automatically created on first run:
expenses: id, date, amount, category, subcategory, note
credit: id, date, amount, source, note
Start the MCP server using either of the following commands:
uv run python expense_tracker.pyOr via the installed package command:
uv run expense-tracker-mcpTool | Parameters | Description |
|
| Add an expense (date defaults to today). |
|
| List expense records with optional date range and limit. |
|
| Group expenses by category and calculate totals. |
|
| Update fields of an existing expense record. |
|
| Delete an expense by ID. |
|
| Add an income or credit record. |
|
| List recent credit entries. |
| (none) | Return total credits, total expenses, and current balance. |
Resource URI | MIME Type | Description |
|
| Provides the category catalog from |
To connect this server to Claude Desktop, add the configuration below to your claude_desktop_config.json:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"expense-tracker": {
"command": "uv",
"args": [
"run",
"--directory",
"C:\\Users\\Dell\\OneDrive\\Desktop\\Expense_tracker_mcp",
"python",
"expense_tracker.py"
]
}
}
}(Replace the path with the absolute path to your project directory).
server.py provides equivalent HTTP endpoints and interactive OpenAPI documentation.
Start the API:
uv run python server.pyAPI Base URL: http://localhost:8000
Interactive Swagger UI: http://localhost:8000/docs
Method | Endpoint | Description |
|
| Add a new expense |
|
| List expenses (supports |
|
| Update an existing expense |
|
| Delete an expense |
|
| Get expense summary by category |
|
| Add a credit / income entry |
|
| List credit entries |
|
| Get current balance |
|
| Retrieve categories catalog |
curl -X POST http://localhost:8000/expenses \
-H "Content-Type: application/json" \
-d '{
"amount": 25.50,
"category": "food",
"subcategory": "dining_out",
"note": "Lunch"
}'All financial records are stored locally in expenses.db within the project root. This file is excluded by .gitignore to prevent sensitive financial data from being committed to version control.
Add credit/income entry.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format (default: today) | |
| note | No | Optional note | |
| amount | No | Credit amount | |
| source | No | Income source (salary, freelance, refund, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure, but it only says 'Add credit/income entry.' It does not disclose ledger side effects, balance updates, return values, reversibility, or validation behavior. 'Add' reveals mutation, but for a financial tool this is a significant behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words and immediately states the operation and resource. It is appropriately short for what it tries to say, though the omitted context is penalized under other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a fully documented optional-parameter schema, the description is minimally usable: an agent knows which business action to perform and can infer argument intent from the schema. It does not describe the resulting state, return behavior, or how the entry interacts with get_balance and list_credits, which is an obvious gap for a financial mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all four parameters with descriptions and defaults, so schema coverage is effectively complete. The tool description only reinforces that this is a credit/income entry and adds no parameter-specific nuance on top of the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Add') and the resource ('credit/income entry'), which is enough to distinguish it from add_expense and list_credits in the sibling list. It does not explicitly frame the sibling contrast, but the resource label is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb and resource imply that this is for adding income/credit entries rather than expenses, summaries, or reads. However, there is no explicit 'use when' guidance or mention of alternatives such as list_credits and get_balance, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new expense entry to the database.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format (default: today) | |
| note | No | Optional note | |
| amount | No | Expense amount | |
| category | No | Expense category | |
| subcategory | No | Optional subcategory |
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, but it only says it writes a new entry to the database. It doesn't mention permissions, amount validation, idempotency, error conditions, or what happens to other data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler and a front-loaded action. It is concise, though the space could have been used to add a bit more behavioral or selection context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter mutation tool with no annotations and no output schema, one sentence is adequate but thin. The schema covers parameter meaning, but the description omits return/effect context, validation behavior, and differentiation from add_credit, leaving several gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a type, default, and description. The tool description adds no additional parameter meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says specifically 'Add a new expense entry to the database,' which conveys the verb and resource. It doesn't explicitly mention sibling tools like add_credit or edit_expense, so it stops just short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call add_expense versus edit_expense, delete_expense, or add_credit. The description only states the operation, leaving all selection context to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an expense entry.
| Name | Required | Description | Default |
|---|---|---|---|
| expense_id | Yes | ID of expense to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description is the only signal about side effects; 'Delete' unambiguously communicates a destructive mutation. It doesn't disclose whether deletion is permanent, idempotent, or whether it affects balance/summary data, but for a simple one-parameter delete the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence containing exactly the needed action and resource; no filler, redundancy, or buried details. It is appropriately sized for a one-parameter delete tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one fully documented parameter and no output schema, the description plus schema is largely sufficient for correct invocation. Minor missing context around side effects and return behavior keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains expense_id as 'ID of expense to delete'. The description adds no parameter detail beyond that, so it meets the baseline but does not contribute extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Delete') and resource ('an expense entry'), stating the tool's function plainly. It is clear enough to distinguish from siblings like add_expense and edit_expense, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb: call this when an expense should be removed. It gives no explicit when-not guidance or alternatives, so the agent must infer the context from the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing expense.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | New date | |
| note | No | New note | |
| amount | No | New amount | |
| category | No | New category | |
| expense_id | Yes | ID of expense to edit | |
| subcategory | No | New subcategory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only states that an existing expense is edited and does not disclose whether updates are partial, how errors like a missing expense_id are handled, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence and contains no wasted words. However, it is so minimal that it borders on under-specification, providing little beyond a literal restatement of the tool's name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no annotations, and no output schema, a one-sentence description is not enough context for an agent to call the tool correctly. Missing context includes update semantics, return value, and error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented as 'New date', 'New amount', etc. The description adds no extra semantic information beyond the schema, meriting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Edit') and the resource ('an existing expense'), distinguishing it from add/delete/list siblings. It does not enumerate which attributes can be changed, but the input schema fills that in.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus add_expense, delete_expense, or list_expenses. The description does not mention typical scenarios, prerequisites, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current balance (total credits - total expenses).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral responsibility. It discloses the calculation formula, which is useful, but does not mention that it is a read-only operation or describe the return value format beyond the balance amount.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that states the operation and its formula. No filler or redundancy exists, and the key meaning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool, the description is nearly complete. It defines what 'balance' means and how it is computed, though it could optionally mention the response type or that it reflects the current snapshot at call time.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to clarify. The baseline of 4 applies because parameters cannot be an issue.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a clear resource ('current balance') and defines the computation ('total credits - total expenses'). This clearly distinguishes it from sibling tools that add, list, or edit individual credits and expenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: call this when you need the current balance. However, it does not explicitly say when not to use it or which sibling alternative should be used in other situations, such as summarize.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List credit entries.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description must carry behavioral information, but it only says 'List credit entries.' It does not disclose side effects, response shape, ordering, or any limitations, though 'list' does weakly imply read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted wording and the key action and object are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The entry is minimal: it states the operation and object but omits when to use this tool, what the returned credit entries look like, whether there is any filtering/ordering, or how it relates to sibling tools like list_expenses/add_credit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the one parameter (limit) with default and description, so the tool description doesn't need to add much. It adds nothing about parameters, but the baseline of 3 applies because coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List credit entries' uses a clear verb and resource, distinguishing it from siblings like list_expenses at a basic level. However, it is almost a restatement of the tool name and adds no detail about scope or filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of a sibling such as list_expenses or search variants, nor any conditions under which it should be called. An agent is left to infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List expense entries. Optionally filter by date range.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20) | |
| end_date | No | End date YYYY-MM-DD (optional) | |
| start_date | No | Start date YYYY-MM-DD (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden. It discloses the optional date-range filter, a meaningful behavioral trait beyond the schema. However, it does not state read-only status, pagination behavior, ordering, or return format. For a simple list tool this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, with the primary purpose front-loaded and the filter option stated efficiently. No filler or redundant content, earning top marks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and full schema coverage, the description is nearly complete. It lacks an explicit output description, but for a list tool this is often understood. The absence of annotations is partially compensated by the clarity of the operation. Overall, it's sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters, so the baseline is 3. The description adds a slight semantic by indicating that start_date/end_date form a date-range filter, which is helpful but minimal. No additional parameter meaning is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('expense entries'), clearly distinguishing it from siblings like add_expense, delete_expense, edit_expense, and list_credits. The purpose is unambiguous even without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (listing expenses) but does not explicitly say when to use this tool versus alternatives. No exclusions or sibling comparisons are provided, though the name and siblings make the context reasonably clear. It falls short of the explicit guidance seen in high-scoring examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize expenses by category. Optionally filter by date range or category.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by specific category (optional) | |
| end_date | No | End date YYYY-MM-DD (optional) | |
| start_date | No | Start date YYYY-MM-DD (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral transparency. It does not state whether the operation is read-only, what the output structure is, or any side effects or limits. 'Summarize' hints at a read-aggregation, but the complete lack of return-format or safety information leaves an agent guessing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that immediately state the core action. There is a slight redundancy ('by category' then 'or category') but no wasted words. It is well sized and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is incomplete for safely invoking this tool. It does not explain what the returned summary contains (e.g., total per category? count? amounts?) or how filters interact. An agent cannot confidently distinguish between an empty result and a malformed output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with descriptions, and whole schema description coverage is 100%. The description only echoes these options ('Optionally filter by date range or category') without adding extra semantic meaning, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Summarize expenses by category.' This is clearer than a vague purpose and is distinguishable from the sibling list_expenses by the inherent difference between summarizing and listing. However, no explicit contrast to sibling tools is given, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied usage context by mentioning optional category and date filters, which indicates this tool handles filtered summaries. But it does not explicitly tell the agent when to prefer this over list_expenses, nor does it mention any exclusions or prerequisites. The intended usage is actionable but not firmly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_creditadd_expensedelete_expenseedit_expenseget_balancelist_creditslist_expensessummarizeScored across 8 tools
Each tool targets a clearly distinct operation: add/list/edit/delete expenses, add/list credits, summarize, and get balance. There are no overlapping or confusable tools; an agent can easily select the correct action.
Most tools follow a consistent verb_noun pattern like add_expense, list_expenses, edit_expense, delete_expense, add_credit. Minor deviations include the bare verb 'summarize' and 'get_balance' instead of something like 'summarize_expenses' or 'get_balance', but the overall pattern remains readable and predictable.
With 8 tools, the set is well-scoped for an expense tracker. There are enough tools to cover core operations without unnecessary redundancy or overwhelming the agent.
Expenses have full CRUD coverage (add, list, edit, delete) and there is summarizing plus balance calculation. However, credits only support add and list, with no edit_credit or delete_credit, which creates a notable gap in managing income entries and could leave incorrect credits uncorrectable.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
