expense-tracker
Provides integration with OpenAI Codex to enable natural language expense logging, parsing amounts, currencies, and dates, and storing expenses in an Excel file.
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 I spent 20 dollars on a Batman figure yesterday"
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 Tracker MCP Server
Enterprise-grade documentation for a Python-based Model Context Protocol (MCP) expense tracking server.
ā ļø Proof of Concept (PoC)
This is a quick and dirty implementation based on frameworks and libraries available as of February 2026.
Behavior, APIs, and integration patterns may evolve in future versions of FastMCP, OpenAI Codex, and related tooling. This is just for demonstrative purposes
Table of Contents
Introduction
Architecture Overview
Environment Setup (uv-based)
Installed Packages
Project Structure
MCP Server Overview
Core Functional Components
Excel Storage Layer
Running the Server
Testing with MCP Inspector
Integrating with Codex in VS Code
Operational Considerations
Future Improvements
1. Introduction
This project implements a local Model Context Protocol (MCP) server using Python and FastMCP.
š¢ Educational Proof of Concept
This repository contains intentionally simple and demonstrative code designed to get started with MCP servers and understand how they work. The implementation prioritizes clarity and approachability over production-grade architecture, advanced patterns, or highly optimized design.
The server allows natural-language expense logging such as:
"I spent 20 dollars on a Batman figure yesterday"
The server:
Parses the amount
Detects currency
Extracts relative or explicit dates
Stores the result in an Excel file
Exposes tools via MCP for AI agents (e.g., OpenAI Codex in VS Code)
This project demonstrates:
Local stdio-based MCP server design
Natural language parsing
Structured data persistence
Tool registration via FastMCP
Integration with OpenAI Codex UI
Example result in Codex on VS Code
![]()
2. Architecture Overview
The solution consists of:
FastMCP stdio server
Natural language parser
Excel persistence layer (openpyxl)
Tool registration via decorators
Local stdio transport for MCP communication
Transport Type: - STDIO (standard input/output)
Data Storage: - Excel file (expenses.xlsx)
Execution Model: - Event-driven tool invocation
3. Environment Setup (uv-based)
The environment was configured using uv for fast dependency
management.
Related MCP server: Expense Tracker MCP Server
Initialize project
uv initAdd required packages
uv add fastmcp openpyxl dateparser pypandocThis creates:
Virtual environment
Dependency resolution
Lockfile
Reproducible environment
4. Installed Packages
Package Purpose
fastmcp MCP server implementation openpyxl Excel read/write operations dateparser Natural language date parsing pypandoc Documentation generation re Regex amount parsing pathlib File handling datetime Timestamp management
5. Project Structure
project-root/
ā
āāā server.py
āāā expenses.xlsx
āāā README.md
āāā .venv/6. MCP Server Overview
The server is initialized as:
mcp = FastMCP("expense-tracker")Tools are registered using:
@mcp.toolThe server starts via:
if __name__ == "__main__":
mcp.run()The server communicates using STDIO and must not print to stdout.
7. Core Functional Components
7.1 _parse_amount(raw)
Extracts numeric amount using regex. Handles: - 12.000,16 - 12,000.16 - 12000
Returns:
float7.2 _parse_currency(raw)
Detects: - $ ā USD - ⬠ā EUR - Ā£ ā GBP - keyword matches (dollars, euro, etc.)
Returns ISO currency code.
7.3 _parse_date_iso(raw)
Uses:
dateparser.search.search_dates()Configuration: - PREFER_DATES_FROM = "past" - RELATIVE_BASE = datetime.now() - RETURN_AS_TIMEZONE_AWARE = False
Returns:
YYYY-MM-DDFallback: - If no date detected ā today
7.4 _parse_expense(text)
Combines: - amount - currency - date - description
Returns structured dictionary:
{
"amount": float,
"currency": str,
"date_iso": str,
"description": str
}8. Excel Storage Layer
Excel file created if missing:
expenses.xlsxHeader structure:
["Date", "Description", "Amount", "Currency", "Raw Text", "Logged At"]Append logic ensures: - Workbook exists - Correct sheet name - ISO timestamp logging
Read logic: - Dynamically maps header row - Avoids tuple index errors - Skips blank rows
9. Running the Server
Direct execution
.\.venv\Scripts\python.exe server.pyThe process should remain running (stdio server).
10. Testing with MCP Inspector
Launch:
npx @modelcontextprotocol/inspector python server.pySteps: 1. Open browser UI 2. View tools 3. Call log_expense 4. Call
list_expenses
11. Integrating with Codex in VS Code
Open Codex MCP UI
"Connect to a custom MCP"
Select: - STDIO
Configuration
Command to launch:
C:\Users\andre\Documents\Python\MCP\Python\Stdio Server\.venv\Scripts\python.exeArguments:
C:\Users\andre\Documents\Python\MCP\Python\Stdio Server\server.pyNo environment variables required.
After saving: - Enable the MCP tool - Use in Codex chat:
Example:
Log this expense: I spent 50 dollars on groceries yesterday12. Operational Considerations
Do not print to stdout
Use stderr for debugging
Always use absolute python path
Ensure virtual environment consistency
Keep Excel closed during writes
Consider file locking for production use
13. Future Improvements
Category auto-detection
Deduplication logic
CSV export
SQLite backend
Multi-user storage
Authentication layer
Cloud deployment (HTTP MCP)
Structured validation with Pydantic
Available Tools
2 toolslist_expensesA
Return the last N logged expenses.
Inputs: limit. Returns: object
log_expenseD
Inputs: text (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: listing expenses and logging a new expense. There is no overlap in functionality.
Both tool names follow a consistent verb_noun pattern with snake_case (list_expenses, log_expense).
With only 2 tools, the server feels underdeveloped for an expense tracker, which typically requires at least CRUD operations. However, the count is not extreme for a minimal prototype.
The tool set lacks essential operations like updating or deleting expenses, and log_expense has no description, making it incomplete for basic expense management.
Maintenance
Related MCP Connectors
Track expenses from your AI chat: log, categorize, monthly CSV reports. All data is local.
Track expenses from receipt photos, then search, summarize and update them from your AI assistant.
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables users to track and manage personal expenses through natural language, including adding entries, filtering by date/category, viewing statistics, and exporting data in JSON or CSV format.3-
- FlicenseNot gradedqualityDmaintenanceEnables users to track expenses by adding, listing, and summarizing them with category support through natural language.-
- FlicenseNot gradedqualityDmaintenanceEnables natural language management of personal expenses, including adding, listing, and summarizing expenses with local SQLite storage.-
- FlicenseAqualityDmaintenanceEnables natural language management of personal expenses, including adding, updating, deleting, searching, and summarizing expenses stored in a local SQLite database.6-