XP投资组合MCP服务器

Quick Start

Add this to your claude_desktop_config.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 below for clone + build instructions if you want to hack on the server.

---

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 } }

---

Demo

After connecting the server, just chat with Claude:

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)

---

Configuring your target allocation

calculate_allocation_drift reads ~/.xp-mcp/allocation.json. A starter file is included at examples/allocation.example.json. Copy it once and edit the percentages:

mkdir -p ~/.xp-mcp
cp examples/allocation.example.json ~/.xp-mcp/allocation.json

The six valid keys are TESOURO, RENDA_FIXA_PRIVADA, FII, ETF, ACAO, FUNDO. 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.

---

Configure your profile

The profile lives at ~/.xp-mcp/advisor-profile.json. Create or update it with set_advisor_profile:

{
  "risk_tolerance": 6,
  "horizon_years": 15,
  "objective": "balanced",
  "monthly_income_target_brl": 3000,
  "excluded_classes": ["FUNDO"],
  "excluded_tickers": ["XYZW3"],
  "notes": "evitar tabaco, prefiro logística e shoppings",
  "outbound_enabled": true,
  "brapi_token": "..."
}

When you flip outbound_enabled to true, the tool requires accept_disclaimer: true in the same call and stamps accepted_disclaimer_at on the saved profile.

Source: brapi.dev

v0.4 uses 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.