expense

The Expense MCP Server provides a local, conversational interface for tracking and analyzing expenses. It exposes a set of MCP tools that you can invoke through an AI assistant like Claude Desktop, Cursor, or other MCP-compatible clients. Core capabilities include adding expenses with categories and descriptions, listing and filtering expenses by date, category, or amount, generating spending summaries, and managing members who share expenses. All data is persisted locally in a JSON file, enabling private, on-device use without sending data to external servers. To use it, configure your MCP client to connect to the expense-tracker server and then issue natural-language commands such as adding expenses, querying for totals, or requesting a breakdown by category. Tools you can call include add_expense, list_expenses, get_summary, add_member, list_members, delete_expense, and update_expense. For example, you can say, “Add a $40 expense for groceries,” “Show me all expenses for this month,” or “What is my total spending this week?” The server supports multiple members, allowing you to track per-person or per-group expenditures and view associated expenses.

Prerequisites

• Python 3.10 or higher
• uv (Python package manager) installed on your system

Installation steps

1. Install uv if you haven’t already: macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

   Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository containing the Expense MCP server and navigate into it: git clone https://github.com/shivamprasad1001/expense-mcp-server.git cd expense-mcp-server

3. Install dependencies via uv: uv sync

4. Run the MCP server using uv: uv run expense-mcp-server

5. (Optional) Test with MCP Inspector or your MCP client to confirm the tools are available and responding.

Tips and common issues:

• Always use absolute paths in your MCP configuration to avoid command-not-found errors. Replace placeholders like /ABSOLUTE/PATH/TO/expense-mcp-server with real paths on your machine.
• If you encounter "No module named 'mcp'", run uv sync in the project directory to install dependencies.
• Ensure the file members.json is writable so data can be persisted between runs.
• When integrating with Claude Desktop or Cursor, restart the MCP client after making configuration changes to ensure the server is loaded correctly.
• The storage is local only; no data is sent to external servers unless you explicitly configure remote tools.
• For troubleshooting server startup issues, verify that the paths in the configuration are absolute and that Python 3.10+ is active in your environment.