How do I use expense-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@expense-mcp add 15 and 27" 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-mcp

by mayankchugh-learning

Overview Schema Related Servers Score Discussions

Python

Local

expense-mcp

A minimal FastMCP server that exposes demo tools for arithmetic and dice rolls. Use it to learn MCP wiring with Claude Desktop or other MCP clients.

Requirements

Python 3.13+ (see .python-version / pyproject.toml)
uv for environments and dependency management

Related MCP server: Calculator MCP Server

Setup with uv (step by step)

Follow these in order on a machine that does not have the project set up yet.

1. Install uv

Pick the official installer for your OS. Common one-liners:

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen the terminal (or reload your shell profile) so uv is on your PATH.

2. Confirm uv

uv --version

3. Get the code

Clone the repository and move into it (use your real clone URL or path):

git clone <repository-url> expense-mcp
cd expense-mcp

If you already have the folder unpacked, just cd to the repo root (where pyproject.toml lives).

4. (Optional) Install a matching Python with uv

If you do not have Python 3.13 available, uv can fetch one:

uv python install 3.13

The repo’s .python-version pins 3.13; uv sync will respect that when creating the environment.

5. Create the virtual environment and install dependencies

From the repo root:

uv sync

This will:

Create .venv if it is missing (or update it to match the lockfile)
Install packages from pyproject.toml using versions from uv.lock

If you prefer to create the venv yourself first (optional):

uv venv --python 3.13
uv sync

6. (Optional) Activate the virtual environment

You do not need activation if you always use uv run … (recommended). To activate:

Windows (PowerShell): .venv\Scripts\Activate.ps1
Windows (cmd): .venv\Scripts\activate.bat
macOS / Linux: source .venv/bin/activate

7. Verify the install

uv run fastmcp --version
uv run python --version

You should see a FastMCP version and Python 3.13.x.

Quick reference (after setup)

Goal	Command
Reinstall deps from lockfile	`uv sync`
Add a new dependency	`uv add <package>`
Refresh `uv.lock` after editing `pyproject.toml`	`uv lock`
Run a one-off command in the project env	`uv run <command>`

Run the server

Development / inspector (useful for debugging tools in the browser):

uv run fastmcp dev inspector main.py

Production-style run (stdio transport for MCP clients):

uv run fastmcp run main.py

Direct Python (stdio, same entry as if __name__ == "__main__"):

uv run python main.py

Tools (API)

Defined in main.py:

Tool	Description
`roll_dice`	Rolls `n_dice` six-sided dice; returns integers.
`add_numbers`	`a + b`
`subtract_numbers`	`a - b`
`multiply_numbers`	`a * b`

Docstrings on each function are what MCP clients show as tool descriptions.

Install into Claude Desktop

uv run fastmcp install claude-desktop main.py

Then:

Restart Claude Desktop fully (quit the app, not only the window).
In settings, ensure the expense-mcp (or similarly named) server is enabled.
If the install command errors (especially on Windows), see Claude Desktop: config path / install fails.

Troubleshooting

Use this section when something fails or behaves unexpectedly. Work from the top of each subsection that matches your symptom.

uv and Python

Symptom	What to try
`uv` is not recognized	Install uv (see Setup), then restart the terminal. Confirm install docs for your OS put `uv` on `PATH`.
`uv sync` fails or wrong Python	Run `uv python install 3.13`, then `uv sync` again from the repo root (folder that contains `pyproject.toml`).
Packages seem missing	From repo root: `uv sync`. Prefer `uv run <command>` so the project `.venv` is used; avoid mixing in a global `python` without the venv.
“No `pyproject.toml`” or wrong deps	`cd` to the repository root before `uv sync` / `uv run`.

Windows: PowerShell and scripts

Symptom	What to try
Running `.venv\Scripts\Activate.ps1` fails (“running scripts is disabled”)	For your user only: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` in PowerShell, then retry. Or use cmd and `.\venv\Scripts\activate.bat`.
Activation not needed	Using `uv run …` from the repo root avoids activation entirely.

Server / dev inspector

Symptom	What to try
`ModuleNotFoundError` or wrong `fastmcp`	Run with `uv run` (e.g. `uv run fastmcp dev inspector main.py`), not a system-wide `python` that never had deps installed.
Inspector / dev command errors	Run from repo root; pass `main.py` or a path that exists. If a port is busy, close other inspector sessions or see FastMCP docs for port options.
Stdio server exits immediately	In a terminal: `uv run fastmcp run main.py` or `uv run python main.py` and read the traceback. Fix any import or config error before wiring Claude again.

Claude Desktop: MCP does not connect or server errors

Symptom	What to try
Server disabled	Settings → MCP: turn on the expense-mcp entry; restart Claude.
Wrong working directory	The MCP process must run with `cwd` (or equivalent) set to this repo so `main.py` and `.venv` resolve. Re-run `uv run fastmcp install claude-desktop main.py` or edit `claude_desktop_config.json` so the launched command’s working directory is the project root.
`uv` not found when Claude starts	Use the full path to `uv.exe` in config, or ensure the user PATH seen by the desktop app includes uv (often differs from your interactive terminal).
JSON config mistakes	Open `claude_desktop_config.json` in an editor with JSON validation. One missing comma breaks the whole file.

Manual config shape (illustrative) — names and keys follow your Claude Desktop version; adjust paths:

"mcpServers": {
  "expense-mcp": {
    "command": "C:\\Users\\you\\AppData\\Local\\Programs\\uv\\uv.exe",
    "args": ["run", "fastmcp", "run", "main.py"],
    "cwd": "C:\\path\\to\\expense-mcp"
  }
}

On macOS/Linux use forward slashes and typical uv location from which uv. Re-installing via fastmcp install is usually easier than hand-editing.

Claude Desktop: config path or install fails (Windows Store and paths)

Classic path (many installers): %APPDATA%\Claude (contains claude_desktop_config.json).

Microsoft Store build often uses:

%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude

If fastmcp install claude-desktop says Claude has no config folder or cannot find it:

Environment variable — set the directory that actually holds claude_desktop_config.json (names depend on FastMCP version):
- FASTMCP_CLAUDE_DESKTOP_CONFIG_DIR, or
- CLAUDE_DESKTOP_CONFIG_DIR
  Then run uv run fastmcp install claude-desktop main.py again in the same terminal session.
Patch in .venv (advanced) — Patching fastmcp\cli\install\claude_desktop.py under .venv can teach the installer to scan Packages\Claude_*\LocalCache\Roaming\Claude. Any later uv sync or fresh venv removes that patch — re-apply or use option 1 or 3.
Directory junction — If %APPDATA%\Claude does not already exist as a real folder, junction it to the Store path (adjust <your-id>; may need an elevated cmd):
```
mklink /J "%APPDATA%\Claude" "%LOCALAPPDATA%\Packages\Claude_<your-id>\LocalCache\Roaming\Claude"
```
Then run uv run fastmcp install claude-desktop main.py again.

Upstream FastMCP may add first-class support for the Store layout so patching or junctions are unnecessary.

Assistant answers without using your tools

A normal-looking answer (e.g. “8 + 10 = 18”) does not prove the MCP ran. Check for tool-use in the UI or force a unique tool.

UI — Look for a tool / “used …” step, not only the final message.
Explicit instruction — e.g. “Use the add_numbers tool from expense-mcp for 8 and 10 and state that you used the tool.”
Unique tool — e.g. “Call roll_dice with n_dice=4.” Matching tool name and die results implicates this server (unless another MCP defines the same tool name).
Proof tool — Add a tiny tool in main.py that returns a string only this project would emit; call it once and compare the tool output.

Patches or local edits under `.venv` disappeared

Anything changed only inside .venv (including hand-patched FastMCP files) is replaced when you run uv sync, delete .venv, or reinstall deps. Prefer env vars, junctions, or documented config over long-lived venv edits; otherwise re-apply the patch after each sync.

Project layout

Path	Role
`main.py`	FastMCP server and `@mcp.tool` definitions
`pyproject.toml`	Package metadata and dependencies
`uv.lock`	Locked dependency versions

Available Tools

3 tools

add_expenseA

Insert one expense row and return the new row id.

Args: date: Calendar date of the expense, preferably YYYY-MM-DD. amount: Monetary amount (positive number). category: High-level label (e.g. food, transport). subcategory: Optional finer grouping (default empty string). note: Optional free text (default empty string).

Returns: A dict with status "ok" and id set to the new SQLite INTEGER PRIMARY KEY, or None if the driver does not expose it.

ParametersJSON Schema

Name	Required	Description	Default
`date`	Yes
`note`	No
`amount`	Yes
`category`	Yes
`subcategory`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the return value behavior, including the possibility of None. It also provides a date format hint. However, it does not mention any side effects, authentication needs, or rate limits, though for a simple insert tool this is adequate. Annotations are missing, so the description carries full burden.

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 well-structured with 'Args' and 'Returns' sections. Every sentence adds value, and there is no redundant or extraneous text. It is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all necessary information: what the tool does, how to use each parameter, and what to expect as output. It is complete for a tool of this complexity, especially given the presence of an output schema (even if not provided in the input, the description explains it).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by providing semantic meaning for each parameter: date format, amount as positive monetary value, category as high-level label, and optional fields with defaults. This exceeds the bare schema definition.

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 clearly states the verb 'Insert', the resource 'expense row', and the return value 'new row id'. It distinguishes itself from sibling tools 'list_expenses' and 'summarize' by being the only write operation.

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 description implies usage for adding an expense, but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_expensesA

Return all expenses with date between start_date and end_date, inclusive.

Rows are ordered by id ascending.

Args: start_date: Range start, YYYY-MM-DD recommended. end_date: Range end, YYYY-MM-DD recommended.

Returns: List of dicts with keys id, date, amount, category, subcategory, note.

ParametersJSON Schema

Name	Required	Description	Default
`end_date`	Yes
`start_date`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses ordering (by id ascending), inclusive date range, and return structure (list of dicts with specific keys). Does not mention permissions, rate limits, or pagination, but for a simple read operation this is adequate.

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?

Description is concise with no wasted words. It uses clear sectioning (Args, Returns) and front-loads the core purpose in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema (contextual signal), the description fully covers behavior: filtering, ordering, and return format. No gaps for an agent to misuse the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description compensates by explaining start_date and end_date as range bounds with recommended format 'YYYY-MM-DD'. This adds meaning beyond the schema's simple type declaration.

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?

Description clearly states the tool returns expenses filtered by date range, ordered by id ascending. It distinguishes itself from sibling tools 'add_expense' (adds) and 'summarize' (aggregates) by focusing on filtering and listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context about date range filtering and order, and implies listing over adding/summarizing. However, no explicit when-not-to-use or alternative tool names are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

summarizeA

Aggregate total spend per category over a date range.

Args: start_date: Range start, YYYY-MM-DD recommended. end_date: Range end, YYYY-MM-DD recommended. category: If set, only this category is included in the aggregation.

Returns: List of dicts with keys category and total_amount (sum of amount). Sorted by category ascending.

ParametersJSON Schema

Name	Required	Description	Default
`category`	No
`end_date`	Yes
`start_date`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the return format (list of dicts with category and total_amount, sorted) and the filtering capability. However, it does not explicitly state that the tool is read-only or non-destructive, which would be helpful.

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 concise, with clear Args and Returns sections. Every sentence serves a purpose, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema (implied by context), the description adequately covers purpose, parameters, and return value. No critical gaps are evident for a basic aggregation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description fully compensates by explaining each parameter: start_date and end_date with recommended format YYYY-MM-DD, and category as an optional filter. This adds significant meaning beyond the schema.

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 clearly states the tool aggregates total spend per category over a date range, using a specific verb and resource. It differentiates itself from siblings (add_expense, list_expenses) by focusing on aggregation rather than individual entries.

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 description explains what the tool does but does not provide explicit guidance on when to use it over alternatives like list_expenses. It implies that it is suitable for summarized data, but lacks when-not or contrast with siblings.

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. Dates show when Glama detected each change.

3 tool updatesv0.1.0Jul 29, 2026
- First observedadd_expense
- First observedlist_expenses
- First observedsummarize

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Disambiguation5/5

Each tool has a distinct purpose: adding an expense, listing expenses by date range, and summarizing spending by category. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (add_expense, list_expenses, summarize). The pattern is predictable and clear.

Tool Count5/5

With 3 tools, the server is well-scoped for its purpose of basic expense tracking. The count is neither too few nor too many for the apparent domain.

Completeness4/5

The tool surface covers adding, listing, and summarizing expenses, which covers core use cases. However, it lacks update and delete operations, which are minor gaps for complete lifecycle management.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
smithery-ai-cookbook-python-quickstart
ai.smithery
A simple MCP server built with FastMCP and python
Developer Tools
213
Aman-Amith-Shastry-scientific_computation_mcpOAuth
ai.smithery
This MCP server enables users to perform scientific computations regarding linear algebra and vect…
Research & Data
22
Math MCP Learning A
io.github.clouatre-labs
Educational MCP server with 17 math/stats tools, visualizations, and persistent workspace
Education & Learning Tools Research & Data Developer Tools
1725

Related MCP Servers

Demo MCP Server
Developer Tools
SannketNikam
F
license
B
quality
D
maintenance
A simple demonstration MCP server that provides basic utility tools including dice rolling and number addition functionality. This server serves as a tutorial example for setting up both local and remote MCP servers using FastMCP.
Updated a year ago (2025-10-01 09:54 UTC)
3
-
Calculator MCP Server
Developer Tools
surajkumar0203
F
license
Not graded
quality
D
maintenance
A simple MCP server that provides basic calculator functionality for performing mathematical operations. Built with FastMCP and demonstrates fundamental MCP server implementation patterns.
Updated a year ago (2025-10-09 09:11 UTC)
-
MCP Calculator Demo
Developer Tools
FisherSkyi
F
license
Not graded
quality
D
maintenance
A sample MCP server that provides basic arithmetic tools like addition, subtraction, multiplication, and division. It serves as a demonstration for implementing the Model Context Protocol and connecting custom tools to clients like Claude Desktop.
Updated 6 months ago (2026-03-15 09:23 UTC)
-
Simple Calculator MCP Server
Developer Tools
KeerthiNingegowda
A
license
Not graded
quality
D
maintenance
Enables basic arithmetic operations (add, subtract, multiply, divide, modulo) via natural language, with a FastMCP-based server and client for exploring MCP tool calling.
Updated a year ago (2025-05-03 16:59 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mayankchugh-learning/local-expense-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

expense-mcp

Requirements

Setup with uv (step by step)

1. Install uv

2. Confirm uv

3. Get the code

4. (Optional) Install a matching Python with uv

5. Create the virtual environment and install dependencies

6. (Optional) Activate the virtual environment

7. Verify the install

Quick reference (after setup)

Run the server

Tools (API)

Install into Claude Desktop

Troubleshooting

uv and Python

Windows: PowerShell and scripts

Server / dev inspector

Claude Desktop: MCP does not connect or server errors

Claude Desktop: config path or install fails (Windows Store and paths)

Assistant answers without using your tools

Patches or local edits under .venv disappeared

Project layout

Available Tools

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Patches or local edits under `.venv` disappeared