# Portfolio Mcp > Local-first, read-only MCP server to talk to your XP Investimentos portfolio through Claude Desktop. TypeScript + SQLite. Zero scraping, zero credentials. - **Type:** MCP server - **Install:** `agentstack add mcp-satsuj1n-portfolio-mcp` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [Satsuj1n](https://agentstack.voostack.com/s/satsuj1n) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Satsuj1n](https://github.com/Satsuj1n) - **Source:** https://github.com/Satsuj1n/portfolio-mcp - **Website:** https://github.com/Satsuj1n/xp-mcp#demo ## Install ```sh agentstack add mcp-satsuj1n-portfolio-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # portfolio-mcp **Talk to your XP Investimentos portfolio through Claude β€” 100% local, read-only, zero scraping.** [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) [](./LICENSE) [](https://www.npmjs.com/package/portfolio-mcp) [](#roadmap) --- ## What is this? `portfolio-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes your **XP Investimentos** portfolio to Claude Desktop (or any MCP-compatible client). You feed it the official PDF/CSV exports XP already gives you β€” the server parses them, normalizes everything into a local SQLite database, and answers questions through MCP tools. - πŸ”’ **Local-first** β€” data lives in `~/.xp-mcp/data.db`. Core tools make zero outbound HTTP calls; advisor tools (v0.4+) are opt-in. - πŸ“΅ **No credentials, no scraping** β€” you control what goes in (PDF/CSV exports). - πŸ‘ **Read-only by design** β€” no tool can place orders or modify anything at XP. - 🧱 **Stdio transport** β€” Claude spawns the process; nothing listens on a port. > Built for personal use, but the architecture works for any custodian that lets you export reports (Rico, NuInvest, Inter, Avenue, ...). PRs welcome. --- ## Why does this exist? Custodian apps are great at *"show me what I have"* but terrible at: - *"Compare my current allocation against my target portfolio."* - *"Which of my CDBs mature in the next 12 months?"* - *"What's my real yield-to-maturity weighted by position size?"* - *"How concentrated am I in a single issuer's FGC limit?"* MCP lets you bolt that intelligence onto Claude **without** giving the LLM provider your credentials, sending your positions to a third-party SaaS, or trusting browser-scraping that breaks every quarter. --- ## Demo After connecting the server, just chat with Claude: ```text You: Liste minhas posiçáes agrupadas por classe de ativo. Claude (using portfolio-mcp.get_positions): TESOURO (53.28%) R$ 16,644.31 β€’ Tesouro Selic 2031 R$ 14,556.80 β€’ Tesouro Selic 2028 R$ 2,087.51 RENDA_FIXA_PRIVADA (20.98%) R$ 6,554.32 β€’ CDB BANCO XP - AGO/2026 - 15,00% R$ 2,203.85 β€’ CDB BANCO XP - SET/2026 - 14,95% R$ 2,197.10 β€’ CDB BANCO XP - OUT/2026 - 14,55% R$ 1,083.63 β€’ CDB BANCO XP - NOV/2027 - 100,00% CDI R$ 1,069.74 FUNDO (10.48%) R$ 3,273.71 ACAO ( 7.44%) R$ 2,325.12 (BBAS3) FII ( 7.81%) R$ 2,439.20 (MXRF11, GTWR11) Total: R$ 31,236.66 You: Quais CDBs vencem em 2026? Claude (filters by asset_class + maturity_date): 3 CDBs maturing in 2026: β€’ Aug/2026 β€” 15.00% pre-fixed R$ 2,203.85 β€’ Sep/2026 β€” 14.95% pre-fixed R$ 2,197.10 β€’ Oct/2026 β€” 14.55% pre-fixed R$ 1,083.63 All issued by BANCO XP S.A. (within single-issuer FGC limit βœ“) You: Estou bem alocado em relação ao meu target? Claude (using portfolio-mcp.calculate_allocation_drift): Lendo ~/.xp-mcp/allocation.json (target: 40% Tesouro, 20% RF, 15% FII, 15% Açáes, 5% ETF, 5% Fundos, tolerΓ’ncia Β±2pp). Mais fora do alvo: β€’ TESOURO: 53.28% (target 40%) β†’ vender ~R$ 4.148 β€’ ACAO: 7.44% (target 15%) β†’ comprar ~R$ 2.362 β€’ FII: 7.81% (target 15%) β†’ comprar ~R$ 2.247 Dentro da banda: β€’ RENDA_FIXA_PRIVADA: 20.98% (target 20%) βœ“ Fora da banda, magnitude menor: β€’ FUNDO: 10.48% (target 5%) β€” vender ~R$ 1.712 β€’ ETF: 0.00% (target 5%) β€” comprar ~R$ 1.562 Net rebalance: -R$ 152 (aporte pequeno sugerido pra fechar). You: Me dΓ‘ um panorama do meu portfΓ³lio. Claude (using portfolio-mcp.get_portfolio_summary): Total: R$ 31.236,66 (12 posiçáes, ref. 2026-05-21) P&L: +R$ 2.736,66 (+9,60% sobre R$ 28.500 investidos Β· 8/12 com P&L computΓ‘vel) Por classe: TESOURO 53,28% R$ 16.644,31 RENDA_FIXA_PRIVADA 20,98% R$ 6.554,32 (+4,04%) FUNDO 10,48% R$ 3.273,71 ACAO 7,44% R$ 2.325,12 FII 7,81% R$ 2.439,20 FGC: R$ 6.554,32 (20,98%) cobertos Vencimentos: curto R$ 5.484 Β· mΓ©dio R$ 16.625 Β· longo R$ 1.070 Β· sem maturity R$ 8.038 Reconciliação: declarado R$ 31.250,00 vs computado R$ 31.236,66 β†’ gap βˆ’R$ 13,34 (βˆ’0,04%, dentro de tolerΓ’ncia) ``` --- ## Architecture ```text β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Claude Desktop β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ stdio (JSON-RPC 2.0) β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” PDF / CSV β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ portfolio-mcp │◀──────────────────────│ XP exports β”‚ β”‚ TypeScript + MCP β”‚ β”‚ (your machine) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ SQL (better-sqlite3, WAL mode) β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ SQLite β”‚ β”‚ ~/.xp-mcp/ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ No network. No credentials. Read-only at XP. ``` **Stack:** TypeScript Β· [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) Β· `better-sqlite3` Β· `pdf-parse` Β· `papaparse` Β· `zod` --- ## Tools | Tool | Purpose | Status | | ----------------------------- | -------------------------------------------------------------------------------------- | :----: | | `import_xperformance_pdf` | Parse XP's official portfolio PDF (XPerformance). Idempotent on re-import. | βœ… | | `import_extract_csv` | Parse a Posição Consolidada / Extrato CSV. Auto-detects delimiter and column aliases. | βœ… | | `get_positions` | List positions with quantity, market value, indexer, maturity. Optional class filter. | βœ… | | `get_portfolio_summary` | Aggregate stats + declared-vs-computed reconciliation gap. Output now includes a `cash_flow_summary` block (YTD + rolling 12m aporte/resgate aggregates) when cash flows have been imported. | βœ… | | `get_transactions` | History of buys/sells | ⏳ | | `get_dividends` | Income / proventos | ⏳ | | `calculate_allocation_drift` | Compare current vs target allocation from `~/.xp-mcp/allocation.json`. Returns drift %, BRL delta, and BUY/SELL suggestions per class. | βœ… | | `set_advisor_profile` | Save the advisor profile (risk, horizon, objective, exclusions, outbound gate, brapi token). | βœ… | | `get_advisor_profile` | Read the saved profile. Returns `exists: false` if not configured. | βœ… | | `get_market_data` | Quotes / fundamentals from brapi.dev for 1-50 tickers, SQLite-cached. Opt-in. | βœ… | | `screen_assets` | Rank B3 FIIs / stocks / ETFs by DY, P/VP, P/L, ROE, market cap. Opt-in. | βœ… | | `import_nota_corretagem` | Parse broker-note PDFs for transaction history | ⏳ | | `import_bank_extract_pdf` | Import a PDF exported from XP's Conta Digital Extrato. Filters for investment-account transfers only (APORTE/RESGATE). Idempotent. | βœ… | | `get_cash_flows` | List cash flows with optional date/kind filters; returns aggregate totals (aporte/resgate/net) over all matching rows. | βœ… | | `suggest_buys` | Suggest BUYs per underweight class using profile objective Γ— asset class matrix (FII/ACAO/ETF). Non-screenable classes (TESOURO/RF/FUNDO) reported in `skipped_classes`. Requires `outbound_enabled=true`. | βœ… | | `calculate_twr` | Time-weighted return (TWR) over XPerformance imports. Modified Dietz chained β€” GIPS-compliant for portfolios without daily NAV. Requires β‰₯ 2 imports. | βœ… | | `calculate_mwr` | Money-weighted return (MWR / IRR) via bisection over signed cash flows. Reports converged=false cleanly when no sign change. Requires β‰₯ 2 imports. | βœ… | | `get_crypto_quote` | Spot crypto quotes in BRL via Mercado Bitcoin. Per-ticker partial failure, 15-min cache, outbound-gated. Quote-only (not yet a tracked asset_class). | βœ… | | `set_crypto_position` | Manually track a crypto holding (`CRIPTO` asset_class). Fetches a live quote, stores a snapshot market value (quantity Γ— price). `quantity: 0` removes it. No cost basis / P&L. Outbound-gated. | βœ… | --- ## Quick Start Add this to your `claude_desktop_config.json`: ```json { "mcpServers": { "portfolio": { "command": "npx", "args": ["-y", "portfolio-mcp"] } } } ``` Config file location: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` Restart Claude Desktop. Done. See [Development](#development) below for clone + build instructions if you want to hack on the server. --- ## How to export from XP XP has no single *"export everything"* button. Try in this order: 1. **XPerformance PDF** *(recommended)* β€” Investimentos β†’ XPerformance β†’ ⬇ PDF. The richest single-file snapshot. 2. **Portal XP web** β€” Investimentos β†’ Posição Consolidada β†’ Exportar CSV 3. **Hub XP / Assessor Digital** β€” Meus Investimentos β†’ Posição β†’ Exportar 4. **Notas de corretagem (PDF)** β€” Conta β†’ Documentos β†’ Notas de Corretagem *(phase 2)* 5. **Extrato de movimentação** β€” Conta β†’ Extrato β†’ filtrar perΓ­odo β†’ Exportar The CSV parser auto-detects `;`, `,`, `\t`, `|` delimiters and fuzzy-matches common XP column names (`Quantidade`, `Qtd`, `PreΓ§o mΓ©dio`, `Valor aplicado`, ...). If a column is missed, extend `HEADER_ALIASES` in `src/parsers/csv-extract.ts`. ### Configuring your target allocation `calculate_allocation_drift` reads `~/.xp-mcp/allocation.json`. A starter file is included at [`examples/allocation.example.json`](./examples/allocation.example.json). Copy it once and edit the percentages: ```bash mkdir -p ~/.xp-mcp cp examples/allocation.example.json ~/.xp-mcp/allocation.json ``` The seven valid keys are `TESOURO`, `RENDA_FIXA_PRIVADA`, `FII`, `ETF`, `ACAO`, `FUNDO`, `CRIPTO`. Values must sum to `1.00` (Β±0.001). `tolerance_pp` is optional β€” when set, drifts within the band are reported as `"ok"` with no action. --- ## Try it without Claude The server speaks JSON-RPC 2.0 over stdio. Smoke test from any terminal: ```bash node dist/index.js **AnΓ‘lise educacional baseada em dados pΓΊblicos. NΓ£o constitui recomendação de investimento. DecisΓ΅es financeiras sΓ£o de sua responsabilidade.** The disclaimer is also returned in `warnings[0]` of every advisor tool that ranks or suggests assets. ### Source: brapi.dev v0.4 uses [brapi.dev](https://brapi.dev) as the sole market-data source. Anonymous calls work for personal use; if you hit rate limits, set `brapi_token` in the profile. Quotes are cached for 60 minutes, fundamentals for 24 hours, universe lists for 7 days. Override per call via `cache_ttl_minutes`. ### Example flow 1. `set_advisor_profile` β€” saves the profile, enables outbound 2. `get_market_data { tickers: ["BBAS3","MXRF11"] }` β€” quotes 3. `screen_assets { asset_class: "FII", criteria: { sort_by: "dividend_yield", order: "desc", filters: { min_dividend_yield_pct: 8 }, limit: 10 } }` --- ## Project layout ```text src/ β”œβ”€β”€ index.ts # MCP server entrypoint (stdio transport) β”œβ”€β”€ tools/ β”‚ β”œβ”€β”€ import-xperformance-pdf.ts # XPerformance PDF β†’ positions β”‚ β”œβ”€β”€ import-extract-csv.ts # XP CSV β†’ positions β”‚ └── get-positions.ts # SQL β†’ positions list with P&L β”œβ”€β”€ parsers/ β”‚ β”œβ”€β”€ pdf-xperformance.ts # PDF text β†’ rows β”‚ β”œβ”€β”€ csv-extract.ts # papaparse + fuzzy header matching β”‚ β”œβ”€β”€ classify.ts # asset-class heuristics + name metadata β”‚ └── normalize.ts # BRL / date / quantity normalizers β”œβ”€β”€ storage/ β”‚ β”œβ”€β”€ db.ts # better-sqlite3 singleton, WAL, env override β”‚ β”œβ”€β”€ schema.ts # CREATE TABLE + AssetClass enum β”‚ └── positions-repo.ts # UPSERT, listPositions, import records └── util/ └── zod-to-json-schema.ts # minimal zod β†’ JSON Schema for MCP ``` --- ## Data model ```text imports every parse attempt with row counts, timestamps, source path positions one row per (asset_class, external_id); upserted on re-import transactions buys/sells from broker notes (phase 2) dividends income / proventos (phase 2) ``` All monetary values are stored as **`INTEGER` cents**. Float math + currency is a well-known source of off-by-a-cent bugs; integers make every aggregation exact. The `UNIQUE (asset_class, external_id)` constraint + `ON CONFLICT DO UPDATE` makes **re-importing the same file idempotent** β€” no duplicates, no manual deduping. --- ## Design decisions worth calling out - **Wide `positions` table with nullable per-class columns.** A table-per-asset-class would be cleaner in theory but adds JOINs for every read, and the column set is small. The wide table fits the access pattern (Claude almost always wants "all positions, maybe filtered by class"). - **Stdio over HTTP.** Claude Desktop spawns the process directly. Zero ports listening, no auth surface, no CORS to misconfigure. Trade-off: no remote clients without a wrapper. - **stderr-only logging.** stdout is the JSON-RPC wire. One stray `console.log` silently corrupts every response. All logs go to stderr, where Claude Desktop captures them into `~/Library/Logs/Claude/mcp-server-xp.log`. - **No price fetching in MVP.** Adding it means a network dependency and a rate-limit problem. When it lands (phase 2), it'll be behind an opt-in env var with a clearly-documented data source. --- ## Privacy - The SQLite file (`~/.xp-mcp/data.db`) is the only place your position data lives. `.gitignore` blocks `*.db`, `*.sqlite`, and `data/` from ever being committed. - The server makes **no outbound HTTP calls** for the core import/inspection tools (`import_xperformance_pdf`, `import_extract_csv`, `get_positions`, `calculate_allocation_drift`). No telemetry. No analytics. - The v0.4 advisor tools (`get_market_data`, `screen_assets`) call brapi.dev **only when `outbound_enabled: true`** in `~/.xp-mcp/advisor-profile.json` and the user has accepted the disclaimer. Disabled by default. --- ## Roadmap - [x] PDF parser for XPerformance (XP's official portfolio report) - [x] CSV parser for Posição Consolidada / Extrato - [x] `get_positions` with class filter, P&L when invested-value is known - [ ] `import_nota_corretagem` (broker-note PDF β†’ transactions) - [ ] CSV parser for proventos export - [x] `calculate_allocation_drift` against `~/.xp-mcp/allocation.json` - [x] v0.3 β€” npm publish + Smithery + awesome-mcp PR - [x] v0.4 β€” Investment advisor foundations: `set_advisor_profile`, `get_advisor_profile`, `get_market_data`, `screen_assets` (brapi.dev, SQLite cache) - [x] v0.5 β€” Portfolio summary + reconciliation gap: `get_portfolio_summary` (aggregate stats, declared-vs-computed gap) - [x] v0.6 β€” Bank extract import + cash flows: `import_bank_extract_pdf` (XP Conta Digital Extrato β†’ `cash_flows` table, schema v3), `get_cash_flows` (filterable query with aggregate totals) - [x] v0.7 β€” Suggest Buys: `suggest_buys` (composes profile + drift + screening into deterministic BUY suggestions per underweight class; non-screenable classes surface in `skipped_classes`) - [x] v0.8 β€” `cash_flow_summary` in `get_portfolio_summary`: YTD + rolling 12m aporte/resgate aggregates in the panorama output (no new tool, additive field). - [x] v0.9 β€” `calculate_twr` + `calculate_mwr`: time-weighted and money-weighted returns over XPerformance imports + cash_flows (Modified Dietz chained + bisection IRR; no schema change; tools MCP 12 β†’ 14). - [x] v0.10 β€” `get_crypto_quote`: spot crypto quotes in BRL via Mercado Bitcoin (`CryptoQuoteSource` interface + `MercadoBitcoinSource` impl; per-ticker partial f … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [Satsuj1n](https://github.com/Satsuj1n) - **Source:** [Satsuj1n/portfolio-mcp](https://github.com/Satsuj1n/portfolio-mcp) - **License:** MIT - **Homepage:** https://github.com/Satsuj1n/xp-mcp#demo Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-satsuj1n-portfolio-mcp - Seller: https://agentstack.voostack.com/s/satsuj1n - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.