Skip to main content
Glama

Servidor MCP de Copilot Money

Consulta y gestiona tus finanzas personales con IA utilizando datos locales de Copilot Money

License: MIT Node.js 18+ TypeScript Tests codecov copilot-money-mcp MCP server

Este es un proyecto independiente impulsado por la comunidad y no está afiliado, respaldado ni asociado de ninguna manera con Copilot Money o su empresa matriz. Esta herramienta fue creada por un desarrollador independiente para permitir consultas mediante IA de datos almacenados en caché localmente. "Copilot Money" es una marca comercial de su respectivo propietario.

Related MCP server: LunchMoney MCP Server

Descripción general

Un servidor MCP que brinda a los asistentes de IA acceso a tus datos de finanzas personales de Copilot Money. Lee desde la base de datos de Firestore (LevelDB + Protocol Buffers) almacenada en caché localmente en tu Mac. Las lecturas son 100% locales sin solicitudes de red.

17 herramientas de lectura sobre gastos, inversiones, presupuestos, objetivos y más: consulta transacciones, cuentas, participaciones, saldos, categorías, cargos recurrentes, presupuestos, objetivos y rendimiento de inversiones.

Privacidad primero

Nunca recopilamos, almacenamos ni transmitimos tus datos a ningún servidor operado por este proyecto; no tenemos ninguno. Consulta nuestra Política de privacidad para obtener más detalles.

  • Sin analíticas, telemetría ni seguimiento de ningún tipo

  • Las lecturas son totalmente locales: cero solicitudes de red

  • Código abierto: verifica el código tú mismo

[!IMPORTANT] Aviso sobre los proveedores de IA. Aunque este servidor se ejecuta localmente y nunca envía tus datos a ningún servidor operado por este proyecto, el asistente de IA al que lo conectes (Claude, ChatGPT, Gemini, etc.) verá tus datos de Copilot Money como parte de la respuesta a tus preguntas. Esto significa que tus datos financieros serán transmitidos y procesados por el proveedor del modelo que elijas (Anthropic, OpenAI, Google u otro tercero), sujeto a la propia política de privacidad y términos de retención de datos de ese proveedor.

Al usar este servidor MCP con un modelo de IA alojado, estás compartiendo conscientemente tus datos financieros con ese proveedor de IA. Solo usa esta herramienta si te sientes cómodo con ese compromiso. Si no es así, considera esperar a una integración oficial de Copilot Money o usar un modelo totalmente local.

Inicio rápido

Requisitos previos

  • Node.js 18+ (viene incluido con Claude Desktop)

  • Copilot Money (versión de la App Store de macOS)

  • Claude Desktop, Cursor o cualquier cliente compatible con MCP

Instalación a través de Claude Desktop

  1. Descarga el paquete .mcpb más reciente desde Releases

  2. Haz doble clic en el archivo .mcpb para instalarlo en Claude Desktop

  3. Reinicia Claude Desktop

  4. ¡Empieza a hacer preguntas sobre tus finanzas!

Instalación a través de npm

npm install -g copilot-money-mcp

Luego, agrégalo a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp"
    }
  }
}

Instalación para Cursor

  1. Instala el paquete globalmente:

    npm install -g copilot-money-mcp
  2. Abre la configuración de Cursor (Cmd + ,) > Features > MCP Servers

  3. Agrega la configuración del servidor:

    {
      "mcpServers": {
        "copilot-money": {
          "command": "copilot-money-mcp"
        }
      }
    }

Qué puedes hacer

Análisis de gastos

"¿Cuánto gasté en comer fuera el mes pasado?"

"Muéstrame todas mis compras en Amazon en los últimos 30 días"

"¿Cuáles son mis 5 categorías de gasto principales este año?"

Utiliza get_transactions, get_categories con rangos de fechas, búsqueda de texto y filtros de categoría.

Resumen de cuenta

"¿Cuál es mi patrimonio neto en todas las cuentas?"

"Muéstrame el saldo de mi cuenta corriente de los últimos 6 meses, mes a mes"

"¿Qué conexiones bancarias necesitan atención?"

Utiliza get_accounts, get_balance_history, get_connection_status.

Cartera de inversiones

"¿Cuáles son mis participaciones actuales y rendimientos totales?"

"Muéstrame el historial de precios de AAPL del último año"

"¿Cuál es mi rendimiento ponderado en el tiempo este trimestre?"

Utiliza get_holdings, get_investment_prices, get_securities, get_investment_performance, get_twr_returns.

Presupuestos y objetivos

"¿Estoy cumpliendo con mis presupuestos este mes?"

"¿Cómo va progresando mi fondo de emergencia?"

"Muéstrame mi historial de objetivos de los últimos 6 meses"

Utiliza get_budgets, get_goals, get_goal_history.

Suscripciones y cargos recurrentes

"¿Qué suscripciones estoy pagando?"

"¿Cuánto gasto en cargos recurrentes al mes?"

Utiliza get_recurring_transactions.

Herramientas disponibles

Herramientas de lectura (17)

Herramienta

Descripción

get_transactions

Consulta transacciones con filtros: rango de fechas, categoría, comerciante, monto, cuenta, ubicación, búsqueda de texto y tipos especiales (extranjeras, reembolsos, duplicados, elegibles para HSA).

get_accounts

Enumera todas las cuentas con saldos, filtra por tipo (corriente, ahorros, crédito, inversión). Incluye cálculo de patrimonio neto.

get_categories

Enumera categorías con recuentos de transacciones y totales de gastos. Admite vistas de lista, árbol y búsqueda.

get_recurring_transactions

Identifica suscripciones y cargos recurrentes con frecuencia, costo y próxima fecha esperada.

get_budgets

Obtiene presupuestos con comparaciones de gastos frente a límites.

get_goals

Obtiene objetivos financieros con montos objetivo, progreso y contribuciones mensuales.

get_goal_history

Instantáneas de progreso mensual para objetivos con datos diarios y registros de contribución.

get_balance_history

Instantáneas de saldo diario para cuentas a lo largo del tiempo. Admite granularidad diaria, semanal o mensual.

get_holdings

Participaciones de inversión actuales con ticker, cantidad, precio, base de costo y rendimiento total.

get_investment_prices

Datos históricos de precios (diarios + alta frecuencia) para acciones, ETF, fondos mutuos y criptomonedas.

get_investment_splits

Historial de divisiones de acciones con ratios, fechas y multiplicadores.

get_investment_performance

Datos de rendimiento de inversión por valor.

get_twr_returns

Datos mensuales de rendimiento ponderado en el tiempo (TWR) para participaciones de inversión.

get_securities

Datos maestros de valores: ticker, nombre, tipo, precio e identificadores (ISIN/CUSIP).

get_connection_status

Estado de salud de la sincronización bancaria para instituciones vinculadas, incluidas las marcas de tiempo de la última sincronización y errores.

get_cache_info

Metadatos de caché local: rango de fechas, recuento de transacciones, antigüedad de la caché.

refresh_database

Recarga los datos desde el disco. La caché se actualiza automáticamente cada 5 minutos.

Configuración

TTL de caché

El servidor almacena datos en caché en la memoria durante 5 minutos. Configúralo mediante la variable de entorno:

# Set cache TTL to 10 minutes
COPILOT_CACHE_TTL_MINUTES=10 copilot-money-mcp

# Disable caching (always reload from disk)
COPILOT_CACHE_TTL_MINUTES=0 copilot-money-mcp

También puedes actualizar manualmente usando la herramienta refresh_database.

Tiempo de espera de decodificación

Para bases de datos grandes (más de 500 MB), aumenta el tiempo de espera de decodificación (predeterminado: 90 segundos):

# Via environment variable
DECODE_TIMEOUT_MS=600000 copilot-money-mcp

# Via CLI flag
copilot-money-mcp --timeout 600000

Para bases de datos de más de 1 GB, aumenta también la memoria de Node.js:

{
  "mcpServers": {
    "copilot-money": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "/path/to/copilot-money-mcp/dist/cli.js",
        "--timeout", "600000"
      ]
    }
  }
}

Períodos de fecha admitidos

El parámetro period admite estos atajos:

this_month last_month last_7_days last_30_days last_90_days ytd this_year last_year

Limitaciones conocidas

Dependencia de caché local

Este servidor lee desde la caché local de Firestore de Copilot Money, no desde la nube. La persistencia sin conexión de Firestore almacena en caché cada documento que la aplicación ha recuperado, por lo que la base de datos local generalmente contiene todas las transacciones, cuentas, presupuestos, objetivos y otros datos que has visto en la aplicación. El tamaño predeterminado de la caché de Firestore es de 100 MB (suficiente para decenas de miles de transacciones), y los documentos más antiguos solo se eliminan mediante la recolección de basura LRU si se supera ese límite.

Para maximizar los datos almacenados en caché: Abre la aplicación Copilot Money y navega por tus datos (historial de transacciones, cuentas, presupuestos) para asegurarte de que se hayan recuperado y almacenado en caché localmente.

Solución de problemas

Base de datos no encontrada

Si ves "Database not available":

  1. Asegúrate de que Copilot Money esté instalado y haya sincronizado los datos

  2. Verifica la ubicación de la base de datos: ~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/main

  3. Verifica que los archivos .ldb existan en el directorio

  4. Proporciona una ruta personalizada: copilot-money-mcp --db-path /ruta/a/la/base/de/datos

Tiempo de espera de trabajador de decodificación agotado

Si ves "Decode worker timed out":

  1. Aumenta el tiempo de espera: copilot-money-mcp --timeout 300000 (5 minutos)

  2. Para bases de datos de más de 1 GB, aumenta también la memoria de Node.js: node --max-old-space-size=4096 dist/cli.js --timeout 300000

No se encontraron transacciones

  • Abre la aplicación Copilot Money y espera a que se sincronice

  • Es posible que la estructura de la base de datos haya cambiado: abre un issue

Contribución

Consulta CONTRIBUTING.md para la configuración de desarrollo, la arquitectura y cómo agregar nuevas herramientas.

Licencia

Licencia MIT: consulta LICENSE para obtener más detalles.

Reconocimientos

  • Creado con MCP SDK por Anthropic

  • Validación de datos con Zod

  • Desarrollado con Bun

Available Tools

14 tools
get_accountsA
Read-only

Get all accounts with balances, plus summary fields: total_balance (net worth = assets minus liabilities), total_assets, and total_liabilities. Optionally filter by account type (checking, savings, credit, investment). Checks both account_type and subtype fields for better filtering (e.g., finds checking accounts even when account_type is 'depository'). By default, hidden accounts are excluded. name is your Copilot nickname when set, else the provider label — it is user-editable, so key on account_id, never on name. Default rows are terse: account_id, name, account_type, subtype, current_balance, institution_name, iso_currency_code, item_id, plus user_hidden / user_deleted when set (the flags include_hidden controls). That drops the other ~35 document fields. PARTIAL list of what goes, not exhaustive: the embedded holdings array (get_holdings covers it), institution logo images plus their logo_content_type (base64-encoded, several KB each — this PAIR is where the removed include_logos flag went, and the flag gated both, so request them together), mask (the last-4 digits humans identify an account by), available_balance, limit, institution_id, creation_timestamp (when the account was created in Copilot, YYYY-MM-DD — written only on newer rows, so absent means unknown, not old), the denormalized official_name / original_* name dupes, and user_id. Any document field is requestable by name: fields: ["default", "mask", "available_balance"], or "all" / "*" for full rows. include_logos was removed in v3.0.0 — passing it now raises an error naming this migration.

Inputs: fields, account_type, include_hidden.

get_balance_historyA
Read-only

Get daily balance snapshots for accounts over time. Each entry returns current_balance, available_balance, limit, account_id, and account_name. The response also includes an accounts array listing the distinct account IDs in the paginated page. Requires a granularity parameter (daily, weekly, monthly) to control response size. Weekly and monthly modes downsample by keeping the last data point per period. Filter by account_id and date range.

Inputs: granularity (required), limit, offset, end_date, +2 more.

get_budgetsA
Read-only

Get budgets from Copilot's native budget tracking. Returns the current-month effective budget per category plus the full amounts map of per-month overrides for history lookups. For parent categories, the returned amount is the resolved total (children + rollovers) that Copilot displays in the Budgets view. Totals use the current-month effective amount.

Inputs: active_only.

get_cache_infoA
Read-only

Get information about the local data cache, including the date range of cached transactions and total count. Useful for understanding data availability before running historical queries. This tool reads from a local cache that may not contain your complete transaction history. Also reports decode_health: per-collection counts of documents dropped on schema validation failure (a "degraded" status means some cached documents are missing from results).

Inputs: no named parameters.

get_categoriesA
Read-only

Unified category retrieval tool. Supports multiple views: list (default) - user categories with transaction counts/amounts for a time period; tree - user categories as hierarchical tree; search - search user categories by keyword. Use parent_id to get subcategories. For list view, use period (e.g., "this_month") or start_date/end_date to filter by date. Includes all categories, even those with $0 spent (matching UI behavior).

Inputs: view, query, period, end_date, +2 more.

get_connection_statusA
Read-only

Get connection status for all linked financial institutions. Shows per-institution sync health including last successful update timestamps for transactions and investments, login requirements, and error states. Use this to check when accounts were last synced or to identify connections needing attention. Also reports decode_health: per-collection counts of cached documents dropped on schema validation failure (a "degraded" status means some documents are missing from results). Also reports scheduled_smoke: the last scheduled API-drift check with timestamp, or null if the weekly job is not installed. Only "fail" means the API drifted; "auth-missing" and "incomplete" mean drift is unknown.

Inputs: no named parameters.

get_goal_historyA
Read-only

Get monthly progress snapshots for financial goals. Returns current_amount, target_amount, daily data points, and contribution records per month. Filter by goal_id or month range (YYYY-MM). Cache-only: no live-mode (--live-reads) counterpart exists because Copilot's GraphQL endpoint does not expose goal data, so this tool always returns cached LevelDB data regardless of the --live-reads flag.

Inputs: limit, offset, goal_id, end_month, +1 more.

get_goalsA
Read-only

Get financial goals from Copilot's native goal tracking. Retrieves user-defined savings goals, debt payoff targets, and investment goals. Returns goal details including target amounts, monthly contributions, status (active/paused), start dates, and tracking configuration. Calculates total target amount across all goals. Cache-only: no live-mode (--live-reads) counterpart exists because Copilot's GraphQL endpoint does not expose goal data, so this tool always returns cached LevelDB data regardless of the --live-reads flag.

Inputs: active_only.

get_holdingsA
Read-only

Get current investment holdings with position-level detail. Returns ticker, name, quantity, current price, equity value, average cost, and total return per holding. Joins data from account holdings, securities, and optionally historical snapshots. Filter by account or ticker symbol. Note: cost_basis may be unavailable for cash-equivalent positions. Positions on hidden and merged accounts are EXCLUDED by default, matching get_accounts — pass include_hidden: true for them. Do NOT sum holdings as portfolio value: unvested stock-plan shares are reported as holdings, so the sum can far exceed the investment balance; with --live-reads use get_investment_balance_live for the total.

Inputs: limit, offset, account_id, ticker_symbol, +2 more.

get_investment_pricesA
Read-only

Get investment price history for portfolio tracking. Returns one row per (security, period) for stocks, ETFs, mutual funds, and crypto. Filter by ticker symbol, date range, or price type (daily/hf). By default each row is TERSE: the security, the period, and its latest price (latest_price / latest_at) — enough to answer "what is this worth". The full price series (prices, an epoch-millis map) is most of a full row and roughly quadruples response size, so it is omitted unless requested via fields; ask for it only when you need the time series itself, not a current value.

Inputs: limit, fields, offset, end_date, +3 more.

get_investment_splitsA
Read-only

Get stock split events from the local Firestore cache. Returns one row per (security, effective_date) with the adjustment multiplier (e.g. 0.1 for a 10-for-1 split — multiply pre-split prices/quantities by this value to convert to the post-split equivalent). Joined with the securities collection so each row includes ticker and name. IMPORTANT: prices returned by get_investment_prices and get_investment_prices_live are ALREADY split-adjusted by Copilot. Use this tool only when you need the split events themselves (e.g., for narrative or historical-analysis purposes) — you do NOT need to apply these multipliers to the prices yourself. Securities that have never split are not included in the output. Coverage is limited to securities Copilot currently syncs in your local cache (typically currently-held or recently-held).

Inputs: limit, offset, end_date, start_date, +1 more.

get_recurring_transactionsA
Read-only

Identify recurring/subscription charges. Combines two data sources: (1) Pattern analysis - finds transactions from same merchant with similar amounts, returns estimated frequency, confidence score, and next expected date. (2) Copilot's native subscription tracking - returns user-confirmed subscriptions stored in the app. Both sources are included by default for comprehensive coverage. Rows in the pattern-analysis recurring array are terse by default: merchant, normalized_merchant, occurrences, average_amount, total_amount, frequency, confidence, category_name, last_date, next_expected_date. That excludes the matched transactions array (already reachable via get_transactions) and confidence_reason (prose explaining the score) — see fields for how to get either back.

Inputs: name, fields, period, end_date, +4 more.

get_transactionsA
Read-only

Reads from the local LevelDB cache, which may lag behind Copilot's server if the macOS app hasn't synced recently. For real-time data use --live-reads with get_transactions_live. Unified transaction retrieval tool. Supports multiple modes: (1) Filter-based: Use period, date range, category, merchant, amount filters. (2) Single lookup: Provide transaction_id to get one transaction. (3) Text search: Use query for free-text merchant search. (4) Special types: Use transaction_type for foreign, refunds, credits, duplicates, hsa_eligible, tagged. (5) Location-based: Use city or lat/lon with radius_km. (6) Tag filter: Use tag to find transactions with a specific tag. Rows are TERSE by default: transaction_id, date, amount, name, category_name, account_id, item_id, pending, excluded, internal_transfer. excluded answers "is this row excluded from spending?" — the raw per-transaction flag OR the row's category being user-excluded, the same union exclude_excluded filters on — so it is true for a row Copilot never stamped individually. It is therefore nearly always false in a default response, since exclude_excluded already removed those rows; it carries information only when you pass exclude_excluded: false. A cache row carries ~30 fields and most callers need a handful, so the rest are excluded unless asked for. PARTIAL list of what that drops, not exhaustive: Plaid metadata (plaid_category_id, plaid_category_strings, plaid_deleted), internal IDs (category_id, recurring_id, goal_id, parent_transaction_id, children_transaction_ids, user_id), enrichment and intelligence fields (normalized_merchant — still the normalized merchant name when requested — intelligence_suggested_category_ids, suggestion_ids, original_name), tag_ids, review state (user_reviewed, user_note, user_changed_type — true only when a human re-typed the row, so do not second-guess its type), location (city, region, country, lat/lon), and flags like is_amazon/from_investment. amazon is worth naming because nothing else hints it exists: on rows Copilot matched to an Amazon order it carries the receipt — {order_id, items: [{id, name, link, price, quantity}], other: {giftWrapping, rewards, savings, shipping, tax}} — so fields: ["default", "amazon"] answers "what was in this order" without an exported CSV. Ask for any of them by name with fields: ["default", "tag_ids"], or take the whole document with fields: ["all"] (or "*"). category_name is always resolved to a human-readable name. compact was removed in v3.0.0 — passing it now raises an error naming this migration.

Inputs: lat, lon, tag, city, +22 more.

refresh_databaseA
Read-only

Refresh the in-memory cache by reloading data from the local Copilot Money database. Use this when the user has recently synced new transactions in the Copilot Money app, or when you suspect the cached data is stale. The cache also auto-refreshes every 5 minutes. Returns the updated cache info after refresh.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 14 tools

    Disambiguation4/5

    Each tool targets a distinct resource (transactions, accounts, holdings, budgets, goals, categories, splits, connection/cache status), and the descriptions steer callers correctly for the closest pairs (get_goals vs get_goal_history, get_accounts vs get_balance_history, get_cache_info vs get_connection_status). The main ambiguity comes from get_transactions being a six-mode mega-tool and from multiple tools referencing absent `_live` counterparts (get_transactions_live, get_investment_prices_live, get_investment_balance_live), which an agent cannot call.

    Naming Consistency5/5

    All tools use snake_case with a get_<resource> pattern, and the single exception (refresh_database) still follows the verb_noun convention. Resource names are predictable and parallel across domains (get_goals/get_goal_history, get_holdings/get_investment_prices).

    Tool Count5/5

    14 tools is well within the sweet spot for a personal-finance server covering transactions, accounts, investments, budgets, goals, and cache management. Each tool maps to a real domain object and none look redundant or padding.

    Completeness4/5

    Read coverage is thorough across every major domain: accounts, transactions (with search/filter/location/tag modes), balance history, budgets, categories, goals plus goal history, holdings, prices, splits, recurring charges, and cache/connection health. The gap is the absence of any mutation tools (edit transaction category, adjust budget/goal, create tags), so agents can analyze but not change anything.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.
      11
      2,329
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server implementation that provides programmatic access to personal finance data through LunchMoney's API, enabling AI assistants to manage transactions, budgets, categories, and assets.
      59
      934 npm
      115
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Splitwise expenses with atomic duplicate prevention, smart fuzzy matching, and support for flexible split ratios between two people.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to perform comprehensive Microsoft Excel operations including data analysis, cell editing, advanced formatting, and VBA execution on Windows systems. It provides a structured workflow for managing workbooks and worksheets through a dedicated Model Context Protocol interface.
      5
      4
      MIT