# ignaciohermosillacornejo/copilot-money-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/ignaciohermosillacornejo/copilot-money-mcp  
**GitHub Stars:** 84  
**npm Downloads (last month):** 911  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ignaciohermosillacornejo-copilot-money-mcp

## Description
Read and manage Copilot Money personal finance data — 30 tools for transactions, budgets, accounts, recurring charges, investments, and goals. Reads are 100% local from the Firestore cache; opt-in writes (--write) go directly to Copilot's GraphQL API.

## Tools
Capabilities this server exposes over MCP:

- **get_transactions** — 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. Returns human-readable category names and normalized merchant names.
- **get_cache_info** — 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).
- **refresh_database** — 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.
- **get_accounts** — 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.
- **get_connection_status** — 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 (pass / fail / auth-missing with timestamp), or null if the weekly job is not installed.
- **get_categories** — 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).
- **get_recurring_transactions** — 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.
- **get_budgets** — 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.
- **get_goals** — 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.
- **get_investment_prices** — Get investment price history for portfolio tracking. Returns daily and high-frequency price data for stocks, ETFs, mutual funds, and crypto. Filter by ticker symbol, date range, or price type (daily/hf). Includes OHLCV data when available.
- **get_investment_splits** — 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).
- **get_holdings** — 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.
- **get_balance_history** — 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.
- **get_goal_history** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "copilot-money-mcp": {
    "command": "npx",
    "args": ["-y","copilot-money-mcp"]
  }
}
```

## Documentation

## What ignaciohermosillacornejo/copilot-money-mcp MCP server does

ignaciohermosillacornejo/copilot-money-mcp exposes Copilot Money personal-finance data through the Model Context Protocol. Its coverage includes transactions, account balances, financial-institution connections, categories, recurring charges, budgets, goals, investment holdings, prices, splits, and balance or goal history.

The default operating mode is local and read-only. The server reads Copilot Money’s cached Firestore data stored in LevelDB and does not make network requests for those reads. This makes it suitable for asking questions about locally available financial history without sending requests to a project-operated service. The connected AI provider may still receive the data needed to answer prompts.

## How it works

Three modes control the available tools:

- Default mode reads the local cache and requires no Copilot authentication.
- `--live-reads` uses Copilot’s GraphQL API for fresher read results and requires a browser session logged in to app.copilot.money.
- `--write` enables mutation tools and automatically turns on live reads, because write operations require server-fresh transaction metadata.

The cache can lag behind Copilot Money when the macOS application has not synchronized recently. `refresh_database` reloads the in-memory cache, which also refreshes automatically every five minutes. `get_cache_info` reports the cached transaction range, count, and decode health, helping identify incomplete or degraded cached collections before analysis.

## Setup and configuration

Copilot Money’s macOS App Store application and Node.js 18 or newer are prerequisites. Install the package globally with `npm install -g copilot-money-mcp`, then register the `copilot-money-mcp` command in an MCP client configuration. Claude Desktop and Cursor are documented clients; the server uses a standard command-based MCP configuration.

For live reads or writes, log in to app.copilot.money using a supported Chromium-based browser, Firefox, or Safari. The server reuses the browser session’s Firebase refresh token. If authentication is absent, the server can still start and prompts for login when the first live or write tool is called. Default cache mode does not need browser authentication.

## Tools and capabilities

Transaction retrieval supports date, period, category, merchant, amount, tag, location, transaction type, transaction ID, and free-text filters. Results include normalized merchant names and readable category names. Other finance workflows include:

- Review account balances, net worth, assets, liabilities, and hidden-account filtering.
- Inspect institution sync health, login requirements, update timestamps, and errors.
- Browse category lists, hierarchies, counts, amounts, and keyword matches.
- Identify recurring charges using transaction patterns and Copilot-confirmed subscriptions.
- Compare current-month budgets and historical monthly overrides.
- Track savings, debt, and investment goals, including monthly progress history.
- Analyze holdings, returns, investment prices, OHLCV data, and cached split events.
- Retrieve daily, weekly, or monthly account balance history.

Live variants are available for selected cache-backed reads. Goal and goal-history tools remain cache-only because Copilot’s GraphQL endpoint does not expose goal data. Investment prices supplied by Copilot are already split-adjusted; split data is intended for examining corporate-action events rather than manually adjusting those prices.

## Limitations and notes

This project is independent of Copilot Money and is not affiliated with or endorsed by Copilot or its parent company. Local results depend on the state and completeness of the Copilot cache, and schema-validation failures can cause documents to be omitted; the cache and connection-status tools expose health information for diagnosing this condition.

Live and write modes send HTTPS requests to Copilot’s GraphQL API and depend on a valid browser session. Write operations are opt-in and should be enabled only when mutation access is appropriate. When using a hosted AI model, financial information is shared with that model provider under its privacy and retention policies, even though this server does not operate an analytics or data-collection service.

_Full upstream README: https://allmcps.com/mcp/ignaciohermosillacornejo-copilot-money-mcp/readme_