Smart Expense MCP lets an AI assistant manage expenses, budgets, recurring items, friends/balances, group events/splits, analytics, and reports through MCP tools.
Create, view, update, soft-delete, restore, list, and filter expenses with metadata such as tags, merchant, location, receipt URL, payment method, category, subcategory, and event.
Manage categories and subcategories: create, rename, change icons, delete, add subcategories, and move them between categories.
Generate analytics: category-wise summaries, monthly/yearly breakdowns, payment-method summaries, budget summaries, and quick dashboard stats.
Set and track monthly category budgets with 🟢/🟡/🔴 alert levels.
Add, list, and process recurring expenses with daily, weekly, monthly, or yearly frequency.
Manage friends and balances: add/list friends, record who paid whom, view friend/overall balances, and settle up.
Create and manage group events: add members, add equal/percentage/custom split expenses, view event summaries, list events, and close events.
Compute minimized settlement transactions with a greedy two-pointer algorithm and explain the algorithm.
Search expenses conversationally and return matching records plus totals, counts, and averages.
Export monthly expenses to CSV or Excel.
Allows automatic creation of expense entries for Netflix subscriptions through the recurring expenses feature.
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., "@Smart Expense Management MCP How much did I spend on food this month?"
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.
Track expenses, split bills with friends, manage group trips, and get spending analytics — all through natural conversation with Claude or ChatGPT.
No app to open, no forms to fill. Just talk.
Built with FastMCP + Python + Neon PostgreSQL, and hosted on Render.
Just talk to Claude or ChatGPT naturally:
"Add ₹450 expense at Domino's, Food category, paid via UPI, tags: dinner, friends."
"How much did I spend on food this month?"
"I paid ₹600 for Rahul for petrol."
"Who owes me money?"
"Create a Girnar Trip event with Rahul, Prince, and Jay."
"Add ₹4000 hotel expense to Girnar Trip, split equally."
"Who owes what in the Girnar trip?"
"Set a ₹5000 budget for Food in July 2026."
"Export July 2026 expenses to Excel."
The AI assistant understands your request, selects the appropriate MCP tool, and performs the operation.
Related MCP server: expense-tracker-mcp-server
Module | What it does |
Expenses | Full CRUD, soft-delete/restore, tags, merchant, location, receipt URL |
Categories | Dynamic categories and subcategories with emoji icons |
Filtering Engine | 15+ dimensions — date, category, amount range, merchant, tags, payment method, event |
Analytics | Monthly/yearly summaries, category breakdown with percentages, budget utilization and alerts |
Splitwise (General) | Record "I paid for X" / "X paid for me" with net balance tracking per friend |
Splitwise (Events) | Group trips with equal, percentage, and custom splits |
Settlement Engine | Greedy two-pointer algorithm to minimize settle-up transactions |
Budgets | Per-category monthly budgets with 🟢 🟡 🔴 alert levels |
Recurring Expenses | Manage recurring entries for Netflix, rent, gym, etc. |
Reports | Export expenses to CSV and Excel ( |
Hosting: Render
MCP Server URL:
https://expense-manager-mcp.onrender.com/mcpDatabase: Neon PostgreSQL
Protocol: MCP over Streamable HTTP
The MCP server is hosted on Render, so you don't need to clone the repository or install Python dependencies to connect your AI assistant.
Simply use the MCP URL above when configuring your connector.
You can connect Smart Expense to Claude using a custom connector.
Open Claude.
Navigate to Settings → Connectors.
Select Add custom connector.
Enter the following details:
Name:
Smart ExpenseMCP Server URL:
https://expense-manager-mcp.onrender.com/mcpSave the connector.
Enable Smart Expense for your conversation.
Start chatting!
Try this prompt:
Add a ₹200 coffee expense today, paid by cash.Claude will connect to your deployed MCP server and use its available tools.
You can also configure the MCP server through Claude Desktop's configuration file.
Open claude_desktop_config.json and add:
{
"mcpServers": {
"smart-expense-mcp": {
"url": "https://expense-manager-mcp.onrender.com/mcp"
}
}
}Save the configuration and restart Claude Desktop.
ChatGPT supports custom remote MCP apps through Developer Mode on supported plans and workspaces.
Follow these steps:
Step 1: Enable Developer Mode
Open ChatGPT.
Navigate to Settings → Apps & Connectors → Advanced Settings.
Enable Developer Mode, if available.
Step 2: Create a Custom App
Open the Apps section.
Select Create.
Choose the option to create a custom app or connector.
Step 3: Enter MCP Details
Use the following configuration:
App Name:
Smart ExpenseMCP Server URL:
https://expense-manager-mcp.onrender.com/mcpSave and create the app.
ChatGPT will discover the tools exposed by the MCP server.
Step 4: Start Using Smart Expense
Open a new conversation.
Select the + button.
Open More and select Smart Expense.
Start interacting with your expense management server.
Try this prompt:
Show my quick stats for this month.ChatGPT will use the connected MCP tools to retrieve the relevant information.
Note: Developer Mode and custom MCP app availability depend on your ChatGPT plan and workspace settings. The exact interface may vary.
Please read this before using the application with real financial data.
Currently, Smart Expense uses a shared database.
This means:
All connected users access the same Neon PostgreSQL database.
User-level data isolation has not yet been implemented.
Expenses and financial records are not independently separated for each user.
Different users may be able to access or modify records belonging to others.
Planned improvement:
Implement proper multi-user authentication and database-level user isolation so that every user can access only their own expenses, friends, budgets, events, and financial records.
Until this improvement is implemented and verified, this deployment should be treated as a development/demo application.
Do not use it for confidential or sensitive financial information.
If you want to run or modify the server yourself:
Python 3.10+
Neon PostgreSQL database
Git
Clone the repository:
git clone https://github.com/<your-username>/expense-agent.git
cd expense-agentInstall dependencies:
uv syncConfigure the database connection and other required environment variables according to the project's configuration.
Run the MCP server:
uv run python src/server.pyThe server will start locally.
Use the local MCP endpoint configured by your FastMCP server when connecting your development assistant.
Smart Expense uses the following architecture:
Claude / ChatGPT
|
|
MCP Protocol
|
|
Render Web Service
|
|
FastMCP Server
|
|
Application Services
|
|
Neon PostgreSQL
|
|
Persistent DatabaseTechnology | Purpose |
Python | Backend development |
FastMCP 3.4.4+ | MCP server and tool integration |
Pydantic 2 | Data validation and schemas |
Neon PostgreSQL | Hosted relational database |
Render | Application hosting |
openpyxl | Excel report generation |
python-dateutil | Date handling |
expense-agent/
│
├── src/
│ ├── server.py # FastMCP entry point
│ ├── config.py # Constants and configuration
│ │
│ ├── database/
│ │ ├── db.py # Database connection manager
│ │ ├── models.py # Database table definitions
│ │ └── migrations.py # Database migrations and seeds
│ │
│ ├── schemas/
│ │ ├── expense.py # Expense schemas
│ │ ├── category.py # Category schemas
│ │ ├── splitwise.py # Friends and event schemas
│ │ └── analytics.py # Analytics response schemas
│ │
│ ├── services/
│ │ ├── expense_service.py # Expense CRUD and filtering
│ │ ├── analytics_service.py # Summaries and budgets
│ │ ├── split_service.py # Friend balances and splits
│ │ └── settlement_service.py # Settlement algorithm
│ │
│ └── tools/
│ ├── expense_tools.py # Expense MCP tools
│ ├── category_tools.py # Category MCP tools
│ ├── analytics_tools.py # Analytics and budgets
│ ├── splitwise_tools.py # Friend and balance tools
│ ├── event_tools.py # Event and group tools
│ └── search_tools.py # Search, stats and reports
│
└── reports/ # Generated reports (local)Tool | Description |
| Add an expense with full metadata |
| Get an expense by ID |
| Update expense information |
| Soft-delete an expense |
| Restore a deleted expense |
| Filter expenses using 15+ dimensions |
create_category · update_category · delete_category · list_categories · create_subcategory · move_subcategory
expense_summary · monthly_summary · yearly_summary · payment_summary · budget_summary · set_budget
add_recurring · list_recurring · process_recurring
add_friend · list_friends · record_balance · settle · friend_summary · overall_balance
create_event · add_event_member · add_event_expense · event_summary · close_event
search_expenses · quick_stats · generate_csv · generate_excel
Smart Expense uses a Greedy Two-Pointer Algorithm to minimize the number of transactions required to settle group debts.
Example:
Suppose:
A owes B ₹100.
B owes C ₹100.
A naive settlement would be:
A → B : ₹100
B → C : ₹100But the optimized settlement is:
A → C : ₹100Instead of two transactions, only one transaction is required.
The algorithm works by separating people with positive and negative balances, sorting them, and repeatedly settling the smaller outstanding amount.
Ask your assistant:
Explain the settlement algorithm with an example.Main dependencies:
fastmcp>=3.4.4
pydantic>=2.0
openpyxl
python-dateutilAdditional PostgreSQL driver and database dependencies are managed through the project's dependency configuration.
Smart Expense uses Neon PostgreSQL as its hosted database.
Important considerations:
Database credentials should be stored in environment variables.
Never commit .env files or database credentials to GitHub.
Keep database connection strings private.
Use appropriate database backups and access controls.
Do not expose sensitive financial information through public deployments.
Multi-user data isolation is not implemented yet.
The current deployment is intended for development and demonstration until proper user authentication and data isolation are implemented.
User authentication and authorization.
Individual user-level database isolation.
Secure multi-user expense management.
Improved recurring expense automation.
Advanced spending insights and AI recommendations.
More detailed financial reports.
Improved dashboard and visualization support.
MIT License — see LICENSE for details.
Built with ❤️ using FastMCP, Python, and Neon PostgreSQL.
Add an expense to a group event and compute per-member splits.
split_type options: "equal" → split evenly among all members (or included_member_ids) "percentage" → supply split_data={"friend_id": percent, ...} summing to 100 "custom" → supply split_data={"friend_id": amount, ...} summing to total
Returns the computed split immediately so you can verify it.
Example: Hotel ₹4000 paid by Neev, split equally among 4 friends: → each owes ₹1000
Inputs: title (required), amount (required), event_id (required), paid_by_friend_id (required), +3 more. Returns: object
Add a friend to an existing event.
Inputs: event_id (required), friend_id (required). Returns: object
Add a friend to track balances with.
Inputs: name (required), email, phone. Returns: object
Add a recurring expense that auto-creates entries when due. frequency: 'daily' | 'weekly' | 'monthly' | 'yearly' next_due_date: YYYY-MM-DD
Examples: Netflix monthly ₹199, Gym monthly ₹1500, Rent monthly ₹8000
Inputs: title (required), amount (required), frequency (required), next_due_date (required), +2 more. Returns: object
Budget vs actual for all categories with budgets set. Returns alert level: 🟢 ok / 🟡 warning (≥80%) / 🔴 danger (≥100%)
Inputs: year (required), month (required). Returns: result
Mark an event as closed (all expenses settled).
Inputs: event_id (required). Returns: object
Create a new top-level expense category. Example: name='Fashion', icon='👗'
Inputs: name (required), icon. Returns: object
Create a group event for expense splitting. member_ids: list of friend IDs to add as participants.
Example: "Girnar Trip" with Rahul (id=1), Prince (id=2), Jay (id=3)
Inputs: title (required), end_date, member_ids, start_date, +1 more. Returns: object
Add a new expense.
Examples:
"₹450 at Domino's for dinner, paid via UPI, category Food"
"Flight ticket ₹3500 for Rahul, category Travel"
Inputs: title (required), amount (required), expense_date (required), tags, +9 more. Returns: object
Add a subcategory to an existing category. Example: category_id=1, name='Biryani'
Inputs: name (required), category_id (required). Returns: object
Delete a category. Subcategories are removed automatically (CASCADE).
Inputs: category_id (required). Returns: object
Soft-delete an expense (can be restored later with restore_expense). The record stays in the database with is_deleted=1.
Inputs: expense_id (required). Returns: object
Complete event summary including:
All expenses
Per-member net balances
Minimum settlement transactions (who pays whom, how much)
This uses the greedy two-pointer algorithm to minimize the number of transactions.
Inputs: event_id (required). Returns: object
Category-wise spending summary. Leave year/month empty for all-time totals.
Inputs: year, month. Returns: result
Explains how the minimal debt settlement algorithm works. Great for learning and interview preparation!
Inputs: no named parameters. Returns: result
Net balance summary with a specific friend. Returns: who owes whom, and by how much.
Inputs: friend_id (required). Returns: object
Export all expenses for a given month as a CSV string. The CSV is also saved to the /reports/ directory.
Inputs: year (required), month (required). Returns: result
Export all expenses for a given month to an Excel file (.xlsx). Returns the file path.
Inputs: year (required), month (required). Returns: result
Get full details of a single expense by ID.
Inputs: expense_id (required). Returns: object
List all categories with their subcategories.
Inputs: no named parameters. Returns: result
List all events (active and closed).
Inputs: no named parameters. Returns: result
List expenses with powerful multi-dimensional filtering.
Examples:
"All food expenses in July 2026" → month=7, year=2026, category_id=<food_id>
"UPI expenses above ₹500 this month" → payment_method='UPI', min_amount=500
"Expenses at Domino's" → merchant='Domino'
"Expenses for Girnar trip" → event_id=<event_id>
Inputs: tags, year, month, notes, +12 more. Returns: result
List all friends.
Inputs: no named parameters. Returns: result
List all active recurring expenses.
Inputs: no named parameters. Returns: result
Full monthly report: total, by category (with %), by payment method, top merchant. Example: year=2026, month=7
Inputs: year (required), month (required). Returns: object
Move a subcategory to a different parent category.
Inputs: subcategory_id (required), new_category_id (required). Returns: object
Net balance summary across ALL friends. Shows total receivable (others owe you) and total payable (you owe others).
Inputs: no named parameters. Returns: object
Breakdown of spending by payment method (UPI, Cash, Card, etc.).
Inputs: year, month. Returns: result
Process all overdue recurring expenses — creates actual expense entries for each one and updates next_due_date. Call this daily or at server startup.
Inputs: no named parameters. Returns: object
Dashboard-style overview: this month's total, category breakdown, and overall balance. Perfect for "Give me a financial overview" or "How am I doing this month?"
Inputs: no named parameters. Returns: object
Record a money exchange with a friend.
direction options: "i_paid" → I paid for them → they owe me ₹amount "they_paid" → They paid for me → I owe them ₹amount
Examples:
"Rahul owes me ₹500 for recharge" → direction='i_paid', friend_id=Rahul's id
"I paid ₹120 for Prince for chai" → direction='i_paid', friend_id=Prince's id
"Jay paid ₹200 for my food at Domino's" → direction='they_paid', friend_id=Jay's id
Inputs: amount (required), direction (required), friend_id (required), reason, +1 more. Returns: object
Restore a previously deleted expense.
Inputs: expense_id (required). Returns: object
Natural language expense search.
Claude should use this when the user asks conversational questions about their spending.
Examples: "How much did I spend on food this month?" "Show me Domino's expenses" "All UPI payments above ₹500 in June" "What did I spend at Girnar trip?" "Show my expensive purchases in 2026"
Returns both the matching expenses AND a quick summary (total, count, avg).
Inputs: query (required), tags, year, month, +6 more. Returns: object
Set or update a spending budget for a category in a specific month/year.
Inputs: year (required), month (required), amount (required), category_id (required). Returns: object
Mark balances with a friend as settled. If amount is given, settle exactly that much; otherwise settle everything.
Inputs: friend_id (required), amount. Returns: object
Rename a category or change its icon.
Inputs: category_id (required), icon, name. Returns: object
Update specific fields of an expense. Only supply what you want to change.
Inputs: expense_id (required), tags, notes, title, +6 more. Returns: object
Month-by-month spending breakdown for an entire year.
Inputs: year (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 38 tools
Each tool serves a distinct purpose: CRUD operations for expenses, categories, friends, events, recurring expenses, plus various summaries and reports. Even overlapping tools like list_expenses and search_expenses have clear differentiators (structured filtering vs natural language). No ambiguity between tools.
Most tools follow a consistent verb_noun pattern (e.g., add_event_expense, list_expenses, create_category). Summary tools use a noun_summary pattern (e.g., budget_summary, monthly_summary), which is also consistent. Minor exceptions like quick_stats (should be get_quick_stats) and settle (verb only) slightly break the pattern, but overall naming is predictable.
With 38 tools, the set is quite large for an expense management server. While each tool has a specific role, the abundance of summary/report tools (8+) and separate list/search functions suggests some redundancy. A more streamlined set (25-30) could reduce cognitive load without losing functionality.
The tool surface covers core CRUD for expenses, categories, friends, events, and recurring expenses, along with settlement, budget tracking, and export features. Notable gaps: missing update/delete for friends, events, and recurring expenses, but these can be worked around. Overall, the essential workflows are supported.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Split bills and collect payments through PayNow (Singapore) from your AI. MCP server for SplitBill.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
