Expense MCP

Rastreador de gastos de código abierto con dos partes:

1. Un servidor FastMCP que almacena gastos en Postgres (Supabase).

2. Una app Android de Expo que actúa como host de MCP. Puedes hablar o escribir un gasto; Claude llama a las herramientas MCP por ti.

Endpoint MCP en vivo:

https://indirect-olive-catshark.fastmcp.app/mcp

Repositorio: github.com/sahaniaditya/expense-mcp

Características

• add_expense — guarda un monto, categoría, fecha y descripción opcional

• get_expenses — lista gastos en un rango de fechas

• data://categories — comestibles, transporte, educación, entretenimiento, salud, otros

• Entrada de voz en Android (“Gasté 250 en comestibles”)

• Horizon / FastMCP Cloud OAuth para el servidor remoto

• Flujo de trabajo de GitHub Actions que compila un APK independiente

Related MCP server: Expense Tracker MCP

Arquitectura

Android app (MCP host)
  → Claude (Anthropic API)
    → FastMCP Cloud / local MCP server
      → Supabase Postgres

La app del teléfono no habla directamente con la base de datos. Claude decide qué herramienta llamar; la app ejecuta esa herramienta contra el servidor MCP.

Servidor MCP

Requisitos

• Python 3.14+

• uv

• Una base de datos Postgres (Supabase funciona)

Base de datos

Crea una tabla expenses:

create table if not exists expenses (
  id uuid primary key,
  price integer not null,
  category text not null,
  date timestamptz not null,
  description text
);

Entorno

Copia .env.example a .env y configura tu cadena de conexión:

SUPABASE_URL=postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT.supabase.co:5432/postgres

Nunca hagas commit de .env.

Ejecutar localmente

uv sync
uv run python main.py

El endpoint MCP HTTP es http://127.0.0.1:8000/mcp.

Inspector:

uv run fastmcp dev inspector main.py

Desplegar

Empuja este repositorio a GitHub, luego crea un proyecto en Prefect Horizon / FastMCP Cloud con el entrypoint main.py:mcp. Agrega SUPABASE_URL como secreto en la configuración de implementación.

Los clientes se conectan a:

https://YOUR-PROJECT.fastmcp.app/mcp

La autenticación de Horizon está activada por defecto. Usa una clave API de Horizon (fmcp_...) o completa el inicio de sesión OAuth desde un cliente.

App Android

El código fuente está en mobile/.

Pruébalo con Expo Go (desarrollo)

Expo Go de Play Store debe coincidir con SDK 54.

cd mobile
npm install
npx expo start

Aún necesitas una computadora ejecutando Metro. Para una instalación solo con el teléfono, usa el APK.

Configuración de la app

1. Abre Connect.

2. Confirma la URL de FastMCP Cloud (ya está prellenada para el servidor alojado).

3. Pega una clave API de Anthropic.

4. Toca Sign in and connect y completa el inicio de sesión de Horizon (o pega una clave API fmcp_).

5. Usa Speak o Add.

La app guarda la sesión y se reconecta en el próximo inicio.

Compilar un APK

GitHub Actions produce un APK de lanzamiento (bundle JS incluido, sin necesidad de Metro):

1. Empuja a main o apk-github-actions, o ejecuta el flujo de trabajo Android APK desde la pestaña Actions.

2. Descarga el artefacto expense-mcp-apk.

3. Descomprime e instala app-release.apk.

4. Desinstala primero cualquier compilación de depuración anterior.

EAS local (opcional, necesita una cuenta de Expo):

cd mobile
npx eas-cli login
npx eas-cli build -p android --profile preview

Estructura del proyecto

main.py              MCP tools and resource
connection.py        Supabase / Postgres connection
mobile/              Expo SDK 54 Android client
.github/workflows/   APK build

Licencia

MIT. Ver LICENSE.