Expense Tracker MCP Server

Un servidor de 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 el MCP Inspector.

📋 Requisitos previos

• Python: 3.10+ (probado con Python 3.14)

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

• Node.js: v22.x o v24.x (LTS) — Requerido para la interfaz de usuario de MCP Inspector

• Claude Desktop (opcional): Para probar herramientas directamente dentro de Claude

Related MCP server: Math Addition MCP Server

🚀 Configuración e instalación

1. Inicializar proyecto y entorno

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

# Install FastMCP
uv add fastmcp

2. Preparar Node.js para la interfaz de usuario de 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

Instale el inspector globalmente o permita que npx lo obtenga:

npm install -g @modelcontextprotocol/inspector

🛠️ Ejecución y desarrollo

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

Para lanzar la interfaz web del MCP Inspector con recarga en caliente:

uv run fastmcp dev inspector main.py

• Mantenga 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>

• Abra ese enlace en su 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. Ajustes de configuración

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

Nota: En Windows, las aplicaciones GUI como Claude Desktop a menudo no heredan el PATH del shell. Especifique siempre la ruta absoluta a uv.exe.

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

3. Reiniciar Claude Desktop

1. Cierre completamente Claude Desktop (asegúrese de que se cierre desde la bandeja del sistema de Windows cerca del reloj).

2. Vuelva a abrir Claude Desktop.

3. Verifique en Configuración > Desarrollador que expense-server esté conectado.

🧰 Herramientas disponibles (actual main.py)

🔧 Solución de problemas

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

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

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

Node.js es anterior a v20.12. Actualice a Node v22+ o v24+ mediante nvm install lts && nvm use 24.

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

Caché de npx corrupta por cambiar de versiones de Node. Ejecute:

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