convez.ai
MCP ServerFinanceiroIntermediário
Parasmani-yogi

Expense Tracker MCP Server

Parasmani-yogi/Expense-Tracker-Local-MCP-Server

Gerencie despesas localmente via Claude com MCP e SQLite

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP local que permite gerenciar despesas pessoais através de linguagem natural com Claude. Armazena dados em SQLite com ferramentas para adicionar, listar, atualizar, deletar e resumir gastos por categoria.

Instalação

$npx convez-ai Parasmani-yogi/Expense-Tracker-Local-MCP-Server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Registrar despesas pessoais conversando com Claude
  • Acompanhar gastos por categoria e período
  • Atualizar ou corrigir lançamentos existentes
  • Gerar relatórios de gastos sem deixar dados em cloud

Veredito

MCP server bem estruturado para quem quer controlar despesas localmente via Claude. Simples de instalar e customizar, com armazenamento SQLite seguro, mas carece de recursos avançados como análise temporal ou exportação de relatórios.

README

A tradução para o português deste README ainda está na fila.

💸 Expense Tracker MCP Server

A lightweight Model Context Protocol (MCP) server built with FastMCP and SQLite that enables AI assistants such as Claude to manage personal expenses through natural language.

The server provides tools for adding, listing, updating, deleting, and summarizing expenses while storing all data locally in a SQLite database.


📚 Table of Contents


🔍 Overview

Expense Tracker MCP Server exposes a set of MCP tools that allow AI assistants to interact directly with your expense data.

Instead of manually maintaining spreadsheets or expense apps, you can simply talk to Claude and ask it to:

  • Record a new expense
  • Update an incorrect entry
  • Delete unwanted records
  • Show expenses for a specific period
  • Summarize spending by category
  • View available categories and subcategories

All expense records are stored locally in SQLite, ensuring that your financial data remains under your control.


✨ Features

  • Local-first SQLite storage
  • FastMCP-powered MCP server
  • Add new expenses with categories and notes
  • View expenses within custom date ranges
  • Generate category-wise spending summaries
  • Update existing expense records
  • Remove incorrect or duplicate entries
  • Configurable categories via JSON
  • Automatic category reload without restart
  • Simple Python codebase for customization
  • Compatible with Claude Desktop and other MCP clients

📁 Project Structure

expense-tracker-mcp/
├── main.py
├── expenses.db
├── categories.json
├── pyproject.toml
└── README.md
FileDescription
main.pyMCP server implementation
expenses.dbSQLite database
categories.jsonExpense categories and subcategories
pyproject.tomlProject dependencies
README.mdProject documentation

⚙️ Requirements

RequirementVersion
Python3.10+
FastMCPLatest
SQLiteIncluded with Python
uvlatest recommended

🚀 Installation

Clone the Repository

git clone https://github.com/Parasmani-yogi/Expense-Tracker-Local-MCP-Server.git
cd Expense-Tracker-Local-MCP-Server

Install Dependencies

Using uv:

uv sync

Or using pip:

pip install fastmcp

▶️ Running the Server

Using uv:

uv run main.py

Using Python:

python main.py

The SQLite database is created automatically on first startup.


🔎 FastMCP Inspector

FastMCP includes a built-in Inspector that allows you to test MCP tools and resources directly from your browser.

Launch the Inspector:

uv run fastmcp dev inspector main.py

The Inspector can be used to:

  • Test MCP tools interactively
  • Inspect tool requests and responses
  • View available resources
  • Debug tool behavior
  • Validate your server before connecting it to Claude Desktop

This is the recommended workflow during development.


🔌 Claude Desktop Integration

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/absolute/path/to/expense-tracker-mcp"
    }
  }
}

Restart Claude Desktop after updating the configuration.


🛠️ Available Tools

add_expense

Create a new expense record.

ParameterTypeRequired
datestringYes
amountfloatYes
categorystringYes
subcategorystringNo
notestringNo

Example

Add an expense - cab ride to dehli last sunday fare was 500Rs.

Request

{
  "date": "2026-06-07",
  "note": "Cab ride to Delhi",
  "amount": "500",
  "category": "Transport",
  "subcategory": "Cab"
}
Response

{"status":"ok","id":1}

list_expenses

Retrieve all expenses within a specified date range.

ParameterTypeRequired
start_datestringYes
end_datestringYes

Example

Show my expenses of May.

Request

{
  "end_date": "2026-03-31",
  "start_date": "2026-03-01"
}
Response

[{"id":14,"date":"2026-03-12","amount":8500.0,"category":"Shopping","subcategory":"Electronics","note":"Laptop bag and accessories"},{"id":15,"date":"2026-03-22","amount":1500.0,"category":"Entertainment","subcategory":"Cinema","note":"Movie tickets + popcorn"},{"id":16,"date":"2026-03-08","amount":4200.0,"category":"Health","subcategory":"Fitness","note":"Gym membership - 3 months"}]

summarize

Generate category-wise spending totals.

ParameterTypeRequired
start_datestringYes
end_datestringYes
categorystringNo

Example

Summarize my expenses for March 2026.

Request

{
  "end_date": "2026-03-31",
  "start_date": "2026-03-01"
}
Response

[{"category":"Entertainment","total_amount":1500.0},{"category":"Health","total_amount":4200.0},{"category":"Shopping","total_amount":8500.0}]


edit_expense

Update an existing expense record.

Only supplied fields are modified.

ParameterTypeRequired
expense_idintegerYes
datestringNo
amountfloatNo
categorystringNo
subcategorystringNo
notestringNo

Example

Update expense ID 15.

Change amount to 2000.

Request

{
  "amount": 2000,
  "expense_id": 15
}
Response

{"status":"ok","expense_id":15,"updated":{"date":"2026-03-22","amount":2000.0,"category":"Entertainment","subcategory":"Cinema","note":"Movie tickets + popcorn"}}

delete_expense

Delete an expense by ID.

ParameterTypeRequired
expense_idintegerYes

Example

Delete expense ID 25.


Request

{
  "expense_id": 25
}
Response

{"status":"ok","deleted_expense_id":25}

📦 Available Resources

expense://categories

Returns all configured categories and subcategories from categories.json.

This resource is loaded fresh on every request, allowing you to modify categories without restarting the server.

Example

Show all available expense categories.

🏷️ Expense Categories

The server includes a structured category system designed to cover most personal and professional spending scenarios.

Each expense consists of:

  • Category → High-level classification
  • Subcategory → More specific spending type

Example

Category: food
Subcategory: groceries

Available Categories

CategoryExamples
foodgroceries, dining_out, snacks
transportfuel, cab_ride_hailing, tolls
housingrent, furnishing, repairs
utilitieselectricity, internet, mobile_phone
healthmedicines, doctor_consultation
educationbooks, courses, workshops
entertainmentmovies, games, streaming
shoppingclothing, electronics, accessories
subscriptionsSaaS, cloud services, newsletters
travelflights, hotels, local_transport
businesshosting, ads, contractor_payments
investmentsstocks, mutual_funds, crypto
personal_caresalon, cosmetics, hygiene
family_kidsschool_fees, toys, events
gifts_donationsgifts, charity, festivals
finance_feesbrokerage, bank_charges
homekitchenware, repairs, cleaning
petfood, vet, grooming
taxesincome_tax, gst
miscuncategorized, other

Customizing Categories

All categories are defined in:

categories.json

You can:

  • Add new categories
  • Add new subcategories
  • Rename existing entries
  • Remove unused categories

Changes become available immediately without restarting the server.


🗄️ Database Schema

CREATE TABLE IF NOT EXISTS expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT ''
);

💬 Example Claude Prompts

Add Expense

I spent ₹450 on groceries today.

List Expenses

Show all expenses from 2026-06-01 to 2026-06-30.

Summarize Expenses

How much did I spend this month by category?

Update Expense

Update expense ID 3.

Change amount to ₹900 and note to "Weekly grocery shopping".

Delete Expense

Delete expense ID 3.

View Categories

What expense categories are available?

🧑‍💻 Development

Run the server locally:

uv run main.py

Database file:

expenses.db

Category configuration:

categories.json

The project is intentionally simple and easy to extend. New tools, resources, reports, analytics, and integrations can be added with minimal changes.


Ver o original no GitHub

Bom para

Relacionados