{
  "markdown": "# wealthapi-mcp\n\nA small **Model Context Protocol (MCP)** server that lets Claude (or any MCP-compatible\nassistant) answer everyday portfolio questions about your wealthAPI account:\n\n> \"What did I spend the most money on last month?\"\n> \"How is my portfolio performing this year?\"\n> \"Show me my five biggest positions.\"\n> \"Which of my investments lost the most value?\"\n\nIt runs locally on your machine. Your bearer token never leaves your computer.\n\n## What is an MCP server?\n\nMCP is an open protocol that lets an AI assistant call tools you control. The assistant\nruns in one process (e.g. Claude Desktop); the MCP server runs as a separate process you\nlaunch. They talk to each other over **stdio** using JSON-RPC: the assistant writes a\n`tools/call` message to the server's stdin, the server runs the tool and writes the\nresult back to its stdout. That's the whole protocol.\n\nNote the distinction: this is an **MCP server**, not an MCP *plugin*. There is no such\nthing as an MCP plugin — plugins (e.g. Claude Code plugins) extend the assistant itself,\nwhile an MCP server is a standalone process the assistant connects to over the protocol.\nAny MCP-compatible client (Claude Desktop, Claude Code, others) can use this server.\n\nConcretely, this repo is a Node script. When Claude Desktop starts it, the script\nregisters its tools, waits for tool calls, and when one arrives, makes an HTTPS request\nto the wealthAPI REST API on your behalf and returns a text summary. No state, no\ndatabase, no server to maintain.\n\nRead more at https://modelcontextprotocol.io.\n\n## The tools\n\nAuth is a wealthAPI API token (`wapi_key_…`) carrying the read scopes (`accounts:read`,\n`investments:read`, `transactions:read`, `profile:read`). All tools are read-only.\n\n### Accounts & cash flow\n\n| Tool | Wraps | Answers |\n|---|---|---|\n| `list_accounts` | `GET /api/v1/accounts` | \"What accounts do I have?\" |\n| `get_account_balances` | `GET /api/v1/accounts/balances` | \"Show my cash balance history\" |\n| `get_portfolio_valuation` | `GET /api/v1/accounts/valuation` (+ `historicValuations`) | \"What is my portfolio worth (today / over time)?\" |\n| `list_transactions` | `GET /api/v1/transactions` | \"What did I spend most on last month?\" |\n| `detect_recurring_transactions` | `GET /api/v1/transactions` | \"What subscriptions / fixed costs do I have?\" |\n| `list_bookings` | `GET /api/v1/bookings` | \"Show my buys / sells / dividends\" |\n| `get_cash_flow_summary` | `GET /api/v1/cashFlowAnalytics/history` | \"Income vs spending per month\" |\n| `get_savings_rate` | `GET /api/v1/cashFlowAnalytics/history` | \"What's my savings rate?\" |\n\n### Portfolio & performance\n\n| Tool | Wraps | Answers |\n|---|---|---|\n| `list_investments` | `GET /api/v2/investments` | \"What do I own and what is it worth?\" |\n| `get_gainers_and_losers` | `GET /api/v1/investments/gainersAndLosers` | \"Best / worst performers\" |\n| `get_portfolio_performance` | `POST /api/v2/performance` | \"How did my portfolio do this year?\" |\n| `get_portfolio_allocation` | `GET /api/v1/investments` | \"How diversified am I by region / sector / asset type?\" |\n| `get_risk_metrics` | `GET /api/v1/riskYieldMetrics` (+ `/investments`) | \"How risky is my portfolio?\" |\n| `get_realized_gains` | `GET /api/v1/performance/realizedGains` | \"What did I realize this year?\" (tax season) |\n\n### Dividends\n\n| Tool | Wraps | Answers |\n|---|---|---|\n| `get_dividend_history` | `GET /api/v1/dividends/history` | \"How much dividend income did I get per year / month?\" |\n| `get_dividend_calendar` | `GET /api/v1/dividends/calendar` | \"When are my next dividend payments?\" |\n| `get_portfolio_yield` | `GET /api/v1/dividends/portfolioYield` | \"What's my dividend yield?\" |\n\n### Market data & profile\n\n| Tool | Wraps | Answers |\n|---|---|---|\n| `search_symbols` | `GET /api/v2/symbols` | \"Find Apple / this ISIN\" |\n| `get_quotes` | `GET /api/v2/quotes` | \"What's the current price?\" |\n| `get_security_fundamentals` | `GET /api/v1/fundamentals/{isin}` (+ `/statistics`) | \"Is this stock expensive?\" (P/E, P/B, F-Score) |\n| `whoami` | `GET /api/v1/users/myself` | \"Which account is this?\" |\n\nThe server also registers prompts (`monthly_review`, `savings_rate_check`,\n`subscription_audit`, `fixed_costs_summary`, `financial_health_check`) that chain these\ntools into guided analyses.\n\nTool registration is gated by `SUPPORTED_TOOLS`/`SUPPORTED_PROMPTS` in `src/index.ts` —\nremove a name there to disable it without deleting code.\n\n## Install\n\nYou need Node 20+ and pnpm.\n\n```bash\ngit clone git@github.com:wealthAPI-eu/wealthapi-mcp.git\ncd wealthapi-mcp\npnpm install\npnpm build\n```\n\nGet a personal bearer token from wealthAPI (your account → API settings).\n\nAdd the server to Claude Desktop's config\n(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"wealthapi\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/wealthapi-mcp/build/index.js\"],\n      \"env\": {\n        \"BEARER_TOKEN\": \"paste-your-token-here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The active tools will appear in the tools panel of any chat,\nand you can ask portfolio questions in plain English.\n\n## How to add a new tool\n\nThe canonical example lives in `src/tools/accounts.ts` — `list_accounts` is ~50 lines\nand shows the whole pattern.\n\n1. Create or open the relevant file under `src/tools/` and write a\n   `register*Tools(server, client)` function that calls `server.registerTool(...)`.\n   Each call takes a name, a `{ description, inputSchema }` object (Zod for the\n   input schema), and an async handler that returns `{ content: [{ type: \"text\", text }] }`.\n2. Import and call your `register*Tools` from `src/index.ts`.\n3. `pnpm build` and restart Claude Desktop.\n\nThat's it. No code generation, no registration files, no boilerplate.\n\n## Layout\n\n```\nsrc/\n  index.ts          Bootstrap: McpServer + StdioServerTransport + register*Tools(...)\n  config.ts         Reads BEARER_TOKEN from env; API base URL is fixed to production\n  api/\n    client.ts       fetch wrapper: GET/POST, query strings, retry on 5xx/429\n    types.ts        TS interfaces for API response shapes\n  tools/\n    accounts.ts     list_accounts, get_account_balances, get_portfolio_valuation\n    allocation.ts   get_portfolio_allocation\n    cash-flow.ts    get_cash_flow_summary, get_savings_rate, detect_recurring_transactions\n    dividends.ts    get_dividend_history, get_dividend_calendar, get_portfolio_yield\n    investments.ts  list_investments, get_gainers_and_losers\n    performance.ts  get_portfolio_performance, get_realized_gains\n    risk.ts         get_risk_metrics\n    securities.ts   search_symbols, get_quotes, get_security_fundamentals\n    transactions.ts list_transactions, list_bookings\n    user.ts         whoami\n  util/\n    logger.ts       Pino → stderr (stdout is reserved for MCP)\n    format.ts       formatCurrency, formatDate, formatTable\ntest/\n  api/\n    client.test.ts  Vitest unit test for the query-string builder\n  tools/\n    *.test.ts       Unit tests for the pure aggregation helpers\n```\n\n## Run tests\n\n```bash\npnpm test\n```\n",
  "bytes": 7083,
  "sha": "ae75eb5f256342547c05d77e029e7f76548805db95e75ac9ee9a0b22c7181754",
  "repo_slug": "wealthapi-eu/wealthapi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_eu_wealthapi_mcp_server_af35bbc9/readme"
}