Expense Tracker MCP Server

Un servidor del Model Context Protocol (MCP) construido con FastMCP (v3.x) y Python, diseñado para proporcionar herramientas y recursos para el seguimiento de gastos a clientes compatibles con MCP, como Claude Desktop y MCP Inspector.

📋 Requisitos previos

• Python: 3.10+ (probado con Python 3.14)

• uv: instalador y resolvedor rápido de paquetes Python (astral.sh/uv)

• Node.js: v22.x o v24.x (LTS) — Requerido para el UI del MCP Inspector

• Claude Desktop (opcional): para probar las herramientas directamente en Claude

Related MCP server: Demo MCP Server

🚀 Configuración e instalación

1. Inicializar el proyecto y el entorno

# Initialize uv project (if starting fresh)
uv init .

# Install FastMCP
uv add fastmcp

2. Preparar Node.js para el UI del MCP Inspector

El MCP Inspector (@modelcontextprotocol/inspector) requiere Node.js v22.19.0+ o v24+. Si se usa nvm-windows:

nvm install lts
nvm use 24

Instala el inspector globalmente o permite que npx lo obtenga:

npm install -g @modelcontextprotocol/inspector

🛠️ Ejecución y desarrollo

Opción A: UI web interactiva (MCP Inspector)

Para ejecutar la UI web del MCP Inspector con recarga en caliente:

uv run fastmcp dev inspector main.py

• Mantén esta ventana de terminal abierta.

• La consola mostrará una URL local con un token de autenticación:

  MCP Inspector Web is up and running at:
     http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=<token>

• Abre ese enlace en tu navegador para probar herramientas, inspeccionar esquemas y ver registros de solicitudes/respuestas en tiempo real.

Opción B: Ejecutar el servidor directamente (STDIO)

Para ejecutar el servidor MCP en modo de entrada/salida estándar:

uv run fastmcp run main.py

(o uv run python main.py)

🤖 Conexión con Claude Desktop

1. Ubicación del archivo de configuración

En Windows, la configuración de Claude Desktop se almacena en:

%APPDATA%\Claude\claude_desktop_config.json

(Ruta completa: C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)

2. Configuración

Agrega la definición de expense-server bajo mcpServers.

Nota: En Windows, las aplicaciones GUI como Claude Desktop suelen no heredar el PATH de la consola. Especifica siempre la ruta absoluta a uv.exe.

{
  "mcpServers": {
    "expense-server": {
      "command": "C:\\Users\\hp\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "g:\\Projects\\expense-tracker-mcp-server",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

3. Reinicia Claude Desktop

1. Cierra completamente Claude Desktop (asegúrate de salir desde la bandeja del sistema de Windows, junto al reloj).

2. Vuelve a abrir Claude Desktop.

3. Revisa Configuración > Desarrollador para verificar que expense-server esté conectado.

🧰 Herramientas disponibles (main.py actual)

🔧 Solución de problemas

1. Unknown command "main.py". Available commands: inspector, apps.

En FastMCP 3.x, fastmcp dev es un grupo de comandos. Usa fastmcp dev inspector main.py en lugar de fastmcp dev main.py.

2. node:util does not provide an export named 'styleText'

La versión de Node.js es anterior a v20.12. Actualiza a Node v22+ o v24+ mediante nvm install lts && nvm use 24.

3. Cannot find native binding (npm optional dependencies bug)

Caché de npm dañada al cambiar de versiones de Node. Ejecuta:

npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm install -g @modelcontextprotocol/inspector