A comprehensive personal finance management system built with FastMCP (Model Context Protocol) for Claude Desktop integration. This server provides secure, authenticated transaction tracking with advanced analytics and reporting capabilities.
- 🔐 Secure Authentication: JWT-based user authentication with password hashing
- 💰 Dual Transaction Types: Track both expenses and income (credits)
- 📊 Advanced Analytics: Category breakdowns, date filtering, and financial summaries
- 🔄 Recurring Transactions: Support for daily, weekly, monthly, and yearly frequencies
- 🏷️ Flexible Categorization: 25+ predefined categories with custom tags
- 📅 Date Range Filtering: Analyze transactions by custom time periods
- 📈 Financial Reports: Monthly reports, balance calculations, and spending insights
- 🔒 User Isolation: Each user sees only their own data
- ⚡ FastMCP Integration: Seamless Claude Desktop integration
IF YOU WANT TO USE THIS SERVER LOCALLY, CLONE THIS REPOSITORY AND SET IT UP AS SHOWN.
- Python 3.13+
- uv
- PostgreSQL 15+
- Claude Desktop (for MCP integration)
Make sure you have uv installed in your system. This system was built using uv. To install uv use -
pip install uv-
Clone the repository:
git clone https://github.com/Poushali-02/Expense-Tracker-MCP-Server.git cd Expense-Tracker-MCP-Server -
Install dependencies:
uv venv .venv\Scripts\activate # windows source .venv/bin/activate # macOs / Linux uv pip install -r requirements.txt
-
Check and run the MCP server:
uv run fastmcp dev main.py # this gives the mcp inspector tool to check all the functions uv run fastmcp run main.py # this runs the server
Since you have uv installed, running this command will add the server to your Claude Desktop:
uv run fastmcp install claude-desktop main.pyOr manually add it to your claude_desktop_config.json:
{
"mcpServers": {
"Expense Tracker MCP Server": {
"command": "uv",
"args": [
"--directory",
"absolute\\path\\to\\ExpenseTrackerMCP",
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"main.py"
],
"env": {},
"transport": "stdio",
"type": null,
"cwd": null,
"timeout": null,
"description": null,
"icon": null,
"authentication": null
}
}
}How to access claude_desktop_config.json:
- Open Claude Desktop
- Click your profile (bottom right) → Settings
- Click "Developer" in the sidebar
- Click "Edit Config" to open the JSON file in your editor
THIS SERVER HAS BEEN DEPLOYED USING fastmcp cloud FOR SETTING UP SEE THIS PART.
If you have Claude Pro account, things are very easy.
- Just go to settings (from your Profile name)
- Click on Connectors
- Click on "Add custom Connector"
- On the popup add a name (e.g: "Transaction Tracker")
- On the URL section add this url - https://transaction-tracker.fastmcp.app/mcp
- Restart Claude
If you are a Claude Free Plan user (like me). Follow these steps
- Open Claude Developer Settings
- Open Claude Desktop
- Click your profile (bottom right) → Settings
- Click "Developer" in the sidebar
- Click "Edit Config" to open the JSON file in your editor
- Add this json to the file:
{
"mcpServers": {
"Transaction Tracker": {
"command": "npx",
"args": [
"mcp-remote",
"https://transaction-tracker.fastmcp.app/mcp"
]
}
}
}Use the Claude client to register with register_user tool (username, password, email, full_name).
Use the Claude client with login_user tool (username, password) to get your JWT token.
Here is the list of tools available right now for this server.
- register_user ✅ - Registers new user
- login_user ✅ - Authentication
- verify_token ✅ - Token validation
- change_password ✅ - Password change
- addTransaction ✅ - Adds transactions to database for user
- get_all_transactions ✅ - Retrieves all transactions
- updateTransaction ✅ - Updates transactions
- delete_transaction ✅ - Deletes transactions
- get_selected_transactions ✅ - Retrieves transactions for date range (example: 2025-12-10 to 2025-12-15)
- get_total_transactions ✅ - Calculates total transactions for a category
- get_top_transaction_categories ✅ - Identifies top 5 expenses and credits
- get_summary ✅ - Generates comprehensive analysis with category breakdown
- getBalance ✅ - Calculates net balance
- monthly_report ✅ - Generates monthly report with summary statistics (example: December 2025)
- expense: Money spent (debits)
- credit: Money received (income/credits)
- completed: Transaction finalized
- pending: Transaction in progress
- cancelled: Transaction cancelled
- none: One-time transaction
- daily: Repeats every day
- weekly: Repeats every week
- monthly: Repeats every month
- yearly: Repeats every year
- Housing & Maintenance (rent, utilities, repairs)
- Transportation (fuel, public transport, car maintenance)
- Groceries & Food (groceries, dining out, restaurants)
- Health & Fitness (healthcare, gym, sports)
- Entertainment & Leisure (movies, games, hobbies)
- Education & Self-Development (courses, books, training)
- Insurance (health, car, home insurance)
- Investment & Financial (investments, savings, banking fees)
- Essential Services (internet, phone, subscriptions)
- And 15+ more categories...
- Password Hashing: bcrypt with salt rounds
- JWT Authentication: Secure token-based access
- User Isolation: Database-level user data separation
- Token Expiry: 24-hour token validity
- Password Requirements: Strong password validation
- Input Validation: Comprehensive parameter validation
- fastmcp>=2.13.3
- asyncpg>=0.31.0
- bcrypt>=4.0.0
- pyjwt>=2.8.0
- python-dotenv>=1.0.0
For questions or issues:
-
Open an issue on GitHub
-
Check the documentation in this README
-
Review the code comments for implementation details
-
Please don't judge