portfolio-mcp

Name: portfolio-mcp
Author: Satsuj1n

finance MCP Server

Local-first, read-only MCP server to talk to your XP Investimentos portfolio through Claude Desktop. TypeScript + SQLite. Zero scraping, zero credentials.

bySatsuj1n

VerifiedInstall Ready

financefinance typescript

5 views11 stars1 forksv0.12.0MIT

View on GitHub Homepage Docs

Why This Matters

Discovered via github-topic:mcp and last synced 3mo ago.

VerifiedInstall Ready

Source: github-topic:mcp
Stars: 11
Last synced: 3mo ago
Install: Instructions detected

Install

1. Install the package

npx -y portfolio-mcp

2. Add to claude_desktop_config.json

{
  "mcpServers": {
    "portfolio-mcp": {
      "command": "npx",
      "args": [
        "portfolio-mcp"
      ]
    }
  }
}

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)

Tools

Resources

Prompts

Standard I/O

Transport

Available Tools (20)

import_xperformance_pdf

Parse XP's official portfolio PDF (XPerformance). Idempotent on re-import.

get_cash_flows

List cash flows with optional date/kind filters; returns aggregate totals (aporte/resgate/net) over all matching rows.

get_transactions

History of buys/sells

Tool

Purpose

get_market_data

Quotes / fundamentals from brapi.dev for 1-50 tickers, SQLite-cached. Opt-in.

get_dividends

Income / proventos

import_nota_corretagem

Parse broker-note PDFs for transaction history

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_advisor_profile

Read the saved profile. Returns `exists: false` if not configured.

get_positions

List positions with quantity, market value, indexer, maturity. Optional class filter.

import_bank_extract_pdf

Import a PDF exported from XP's Conta Digital Extrato. Filters for investment-account transfers only (APORTE/RESGATE). Idempotent.

screen_assets

Rank B3 FIIs / stocks / ETFs by DY, P/VP, P/L, ROE, market cap. Opt-in.

calculate_allocation_drift

Compare current vs target allocation from `~/.xp-mcp/allocation.json`. Returns drift %, BRL delta, and BUY/SELL suggestions per class.

calculate_mwr

Money-weighted return (MWR / IRR) via bisection over signed cash flows. Reports converged=false cleanly when no sign change. Requires ≥ 2 imports.

set_advisor_profile

Save the advisor profile (risk, horizon, objective, exclusions, outbound gate, brapi token).

import_extract_csv

Parse a Posição Consolidada / Extrato CSV. Auto-detects delimiter and column aliases.

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).

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.

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.

Works Well With - Skills

referrals

When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' 'partner program,' 'referral incentive,' 'how to get referrals,' 'customers referring customers,' or 'affiliate payout.' Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch.

1104 starsHas guide

social

When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'Tik

1104 starsHas guide

revops

When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and proc

1104 starsHas guide

schema

When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search

1104 starsHas guide