tuskledger-mcp

Servidor del Protocolo de Contexto de Modelo (MCP) para Tusk Ledger. Proporciona a tu asistente de IA acceso tipado a tus datos financieros personales locales, sin enviar nada fuera de tu máquina.

Qué es esto

Un pequeño paquete de Python que se ejecuta como un servidor local de Protocolo de Contexto de Modelo en tu portátil. Una vez que lo hayas añadido a la configuración de tu cliente de IA (Claude Desktop, Cursor, Cowork, Claude Code, cualquier cosa que hable MCP), tu asistente podrá llamar a herramientas como:

• list_accounts — cada cuenta conectada con saldo + estado de sincronización

• query_transactions — filtrar por fecha, cuenta, categoría, etc.

• search_transactions — búsqueda de texto difusa en comercios y notas

• get_spending_summary — totales por categoría para un rango de fechas

• get_top_merchants — a quién le pagas más

• get_recurring_subscriptions — Netflix, gimnasio, etc.

• get_upcoming_bills — próximos 30 días con saldo acumulado

• get_net_worth — valor actual + tendencia de 12 meses

• get_holdings — cada posición de inversión

• get_investments_summary — resumen de cartera + asignación de activos

• get_retirement_projection — resumen de Monte Carlo para tu escenario guardado

• run_sync — activar una extracción de Plaid

• list_stale_accounts — cuentas con datos obsoletos

El servidor se comunica con tu backend local de Tusk Ledger en http://127.0.0.1:8000. Ningún dato cruza Internet. La "nube MCP" no existe; todo esto es un proceso de Python ejecutándose en tu máquina, hablando con otro proceso de Python en la misma máquina.

Por qué existe esto

Tusk Ledger está diseñado para el usuario asistido por agentes: alguien que puede pedirle a Claude / Cursor / Cowork que haga cosas que no podía hacer solo hace cinco años. El servidor MCP es el movimiento de mayor apalancamiento hacia ese objetivo: tu asistente obtiene acceso tipado y estructurado a tus datos financieros en lugar de tener que analizar la interfaz de usuario de React o adivinar el esquema de la base de datos.

Ejemplos del mundo real una vez instalado:

• "Categoriza los últimos 6 meses de transacciones de Whole Foods como Comestibles en lugar de Compras." → El asistente las consulta, tú confirmas y luego crea una regla.

• "¿Cuánto gasté en café el trimestre pasado?" → 3 segundos, sin clics en la interfaz.

• "Mi patrimonio neto cayó esta mañana, ¿qué lo está causando?" → El asistente extrae cuentas, saldos y transacciones recientes y diagnostica.

• "¿Estoy en camino de maximizar mi HSA este año?" → Lee el fondo HSA + contribuciones hasta la fecha + límite del IRS, y devuelve la diferencia.

Requisitos previos

• Una instalación en ejecución de Tusk Ledger (la aplicación principal)

• Python 3.10+

• Un cliente compatible con MCP (Claude Desktop, Cursor, Cowork, Claude Code, …)

Instalación

Opción A — uvx (recomendado; sin instalación permanente)

Si tienes uv (pip install uv):

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx maneja el entorno de Python aislado; nada contamina tu Python global. El servidor se descarga y se almacena en caché en la primera invocación.

Opción B — pip install desde GitHub

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

Luego apunta tu cliente MCP al binario instalado tuskledger-mcp:

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

(Usa la ruta completa de which tuskledger-mcp si estás usando un venv.)

Opción C — clonar para desarrollo

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Dónde viven las configuraciones del cliente MCP

Después de editar la configuración, reinicia el cliente. El servidor arranca cuando el cliente se inicia y se apaga cuando se cierra.

Configuración

Dos variables de entorno, ambas opcionales:

Ejemplo:

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Autenticación

Esta v0 asume que tu backend de Tusk Ledger se está ejecutando con DEV_BYPASS_AUTH=true (el patrón común de una sola máquina documentado en el README del repositorio principal). Si has mantenido la autenticación habilitada, las llamadas del servidor MCP fallarán con errores 401 y verás el error en la respuesta de tu asistente.

El soporte con autenticación está en la hoja de ruta. Hasta entonces, si deseas tanto autenticación como MCP, ejecuta el backend con DEV_BYPASS_AUTH=true solo cuando estés usando el asistente, y vuelve a cambiarlo cuando hayas terminado.

Lo que este servidor NO hace intencionalmente

Por diseño, la v0 es principalmente de lectura. El servidor no expone:

• Eliminar cuentas, transacciones, reglas o metas

• Modificar el esquema de la base de datos o ejecutar migraciones

• Deshabilitar la autenticación o rotar la clave de cifrado

• Tocar tokens de acceso de Plaid

• Enviar datos a cualquier lugar fuera de 127.0.0.1

La razón: un asistente de IA debería poder ayudarte a entender tus datos y ejecutar operaciones seguras (sincronización, consultas), pero los cambios irreversibles pertenecen a la interfaz web donde puedes ver lo que está a punto de suceder. Podemos añadir herramientas de escritura estructuradas (por ejemplo, "crear una regla") en versiones posteriores con flujos de confirmación explícitos, pero el estándar seguirá siendo alto.

Solución de problemas

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Tu aplicación Tusk Ledger no se está ejecutando. Desde el repositorio principal: ./start.sh.

401 Unauthorized desde cualquier herramienta — La autenticación está activada. Consulta la sección de Autenticación anterior. Ejecuta con DEV_BYPASS_AUTH=true por ahora.

404 Not Found — El backend no tiene el endpoint al que intentamos acceder. Probablemente significa que estás en una versión anterior de Tusk Ledger. Actualiza la aplicación principal, reinicia tu cliente MCP.

Las herramientas no aparecen en tu asistente — El servidor MCP no pudo arrancar. Revisa los registros del servidor MCP de tu cliente (Claude Desktop tiene un elemento de menú "Ver registros del servidor MCP"). Causas comunes: ruta incorrecta en la configuración, Python no está en el PATH, uvx no está instalado.

Verificación de salud general — Desde el repositorio principal de Tusk Ledger: ./tuskledger doctor. Este es el diagnóstico canónico para toda la instalación.

Desarrollo

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

Las pruebas no inician un transporte MCP; ejercitan la capa de despacho directamente con un cliente simulado. El protocolo MCP en sí es solo un envoltorio.

CI ejecuta el mismo conjunto de pruebas en Python 3.10/3.11/3.12 a través de GitHub Actions (ver .github/workflows/ci.yml).

Enlaces del proyecto

• Aplicación principal: https://github.com/BradMorphsters/tuskledger

• Sitio del proyecto: https://www.tuskledger.com

• Para agentes que navegan externamente: https://www.tuskledger.com/llms.txt

• Problemas / discusiones: https://github.com/BradMorphsters/tuskledger-mcp/issues

• Licencia: MIT