# Aifolimizer > Local MCP server that turns Claude into a markets analyst over a live Wealthsimple portfolio. 28 skills, 107 tools, 15 data adapters, all free or free-tier data: no paid subscription, no API key. PII stays on your machine. - **Type:** MCP server - **Install:** `agentstack add mcp-tusharagg1-aifolimizer` - **Verified:** Pending review - **Seller:** [tusharagg1](https://agentstack.voostack.com/s/tusharagg1) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [tusharagg1](https://github.com/tusharagg1) - **Source:** https://github.com/tusharagg1/aifolimizer ## Install ```sh agentstack add mcp-tusharagg1-aifolimizer ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # aifolimizer (**AI** Port**foli**o Opti**mizer**) ***Markets analysis in Claude: any ticker, or your whole Wealthsimple portfolio.*** [](https://github.com/tusharagg1/aifolimizer/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) [](#status--roadmap) **[Setup guide](docs/SETUP.md)** · [FAQ](docs/FAQ.md) · [Track record](TRACK_RECORD.md) · [Security](SECURITY.md) aifolimizer turns Claude into a markets analyst you drive in plain English: fundamentals, technicals, earnings, macro, options, and quant signals on **any ticker, no brokerage account required**. Connect Wealthsimple (optional) and the same tools go portfolio-aware: allocation, concentration, tax-loss, and rebalancing on your real holdings. It runs on your own Claude Pro plan and your own machine, and only tickers and percentages ever leave it. **107 MCP tools, 28 skills, 15 market-data adapters** - every source is free or free-tier, researched to exhaust the viable free options so no paid market-data subscription is ever required. Claude writes the analysis; this project supplies the data integration, privacy filter, forward-test harness, and adapter layer. > **Get started in two commands.** With [Claude Code](https://claude.com/claude-code) and [`uv`](https://docs.astral.sh/uv/getting-started/installation/) installed, run `claude plugin marketplace add tusharagg1/aifolimizer` then `claude plugin install aifolimizer@aifolimizer`, and start asking. No clone, no Python to manage, no servers to run. Stock and market analysis work right away; connecting a Wealthsimple portfolio is optional and comes later. Step-by-step: [Quick start](#quick-start). ### Example prompts ```text /stock-analysis NVDA fundamentals + technicals + news (no account needed) /adversarial-research VFV parallel bull / bear / consensus passes, scored into one thesis /daily-briefing (Wealthsimple) portfolio value, concentration flags, this week's earnings, ranked actions should I add to NVDA? (Wealthsimple) weighs your holding and a crowding score before answering ``` *Results pull live market data, and your real holdings once Wealthsimple is connected.* > **Disclaimer.** Analysis is LLM-generated and can be wrong. Verify before acting. Not financial advice. --- ## Why not just ask Claude directly? Ask a chatbot about your portfolio and it guesses - stale training data, no idea what you hold, a made-up P/E or RSI. aifolimizer changes what Claude works with: - **Real numbers, not guesses.** Prices, fundamentals, technicals, and option Greeks come from live feeds or are computed in-process - Claude reasons over data, not stale training memory. - **Your actual holdings.** Concentration, Canadian tax (TFSA / RRSP / FHSA), crowding, and rebalancing run on your live Wealthsimple positions, not a screenshot you paste in. - **Tracked, not assumed.** Tracked skills log every call with entry, stop, and target and mark to market nightly; deflated-Sharpe and calibration gates flag strategies that are only luck. - **Private by default.** Only tickers and percentages leave your machine. Balances, account numbers, and your name never do. ## Who it's for - **Self-directed investors:** ticker-level research (fundamentals, technicals, earnings, macro, bull/bear theses). Broker-agnostic; no portfolio connection needed. - **Wealthsimple users:** the full portfolio-aware suite on top: allocation health, concentration warnings, rebalancing, tax-loss harvesting, daily briefings on live holdings. - **Quant developers:** a working forward-test reference: walk-forward OOS validation, deflated-Sharpe gates, signal-decay curves, regime-conditional weight tuning. - **MCP integrators:** a real-world tool layout, fallback adapter chain, and PII-filter pattern (107 tools, 15 adapters, 28 skills). ## Features - **Live brokerage portfolio.** Wealthsimple via the unofficial [`ws-api`](https://github.com/gboudreau/ws-api-python): MFA-aware, every account type (TFSA / RRSP / FHSA / Non-Reg / Crypto). Holdings, cost basis, and cash flow from the real account; cross-account aggregation and tax-aware logic run server-side. - **107 MCP tools:** live prices, fundamentals, technicals (SMA / RSI / MACD / Bollinger / Minervini stage), FRED macro, crowding, crypto, insider activity, options chains with Greeks, Reddit + StockTwits sentiment, GDELT geopolitics. Verified on Claude Desktop and Claude Code. - **28 analysis skills:** allocation health, risk, sector rotation, dividends, tax-loss harvesting, pre/post-earnings, macro, and quant anomalies (PEAD, momentum). Auto-trigger on intent, or invoke as slash commands. - **15 data adapters** behind one base class ([`data_sources/base.py`](backend/app/services/data_sources/base.py)): yfinance, Finnhub, Twelve Data, Tiingo, EODHD, Stooq, Massive, Binance, Kraken, Coinbase, CoinGecko, Frankfurter, open.er-api, Alpha Vantage, plus the Wealthsimple broker. `data_router` chains them with circuit-breaker fallback; adding a new feed is one file. - **Forward-tested where tracked.** Two skills (`pre-trade-check`, `position-review`) log every call with entry/stop/target; a nightly job marks them to market for 7/30/90-day win rates and alpha vs XEQT/SPY/TSX/QQQ. The rest are advisory. Wins and losses are in [TRACK_RECORD.md](TRACK_RECORD.md). - **Statistical safeguards.** Walk-forward OOS validation, deflated-Sharpe overfitting gate (Bailey & López de Prado 2014), Brier + ECE calibration, signal-decay curves (1 to 63 days), regime-conditional gating, nightly weight tuner. - **Runs locally.** State in JSONL under `~/.aifolimizer/` and `backend/.claude/context/`; Postgres + Redis optional via `docker compose up -d`. ### Inference & fallback Inference runs inside an existing Claude Pro session - symbols, weights (% of NLV), returns %, and scores reach Anthropic; no dollar balances, no account IDs. If Claude Pro is unavailable (logged out, subscription lapsed, no API key), scheduled skills fall back to free-tier LLMs (GitHub Models, Gemini, OpenRouter, Qwen) routed through `llm_router.py`. Fallback is opt-in - off unless a provider key is set in `.env`. Output is tagged `[fallback: free-LLM]` and quality is meaningfully lower than Claude on adversarial reasoning. Same redaction rules apply (see [Privacy](#privacy)). Full fallback runbook in [scripts/AUTOMATION.md](scripts/AUTOMATION.md) and [docs/FAQ.md](docs/FAQ.md). ## Architecture ``` Claude Code / Claude Desktop (Pro subscription) ↓ invokes .claude/skills/* (28 analysis skills) ↓ calls MCP tools backend/mcp_server.py (FastMCP - 107 tools) ↓ uses app/services/* (75+ service modules) ↓ Wealthsimple GraphQL | yfinance | FRED | CoinGecko | … ↓ Postgres (TimescaleDB) + Redis (optional, via Docker) JSONL state files (always - ~/.aifolimizer/, backend/.claude/context/) ``` ## Living docs These three files update as the project runs: - [TRACK_RECORD.md](TRACK_RECORD.md) - every recommendation, marked to market nightly - [.claude/context/lessons.md](.claude/context/lessons.md) - corrections from sessions, do-not-repeat rules - [.claude/context/changes.md](.claude/context/changes.md) - change log ## Status & Roadmap A single-user local tool today: Wealthsimple as the broker, free delayed data (yfinance / FRED / CoinGecko), quant logic and core services under test. Multi-broker, multi-user (OAuth/SSO), and audit logging are natural next steps; open an issue if you'd use them. ## Good to know - Advisory only: no auto-trading, you place every trade. - Wealthsimple access uses the unofficial reverse-engineered `ws-api`; it can break on a WS release and may conflict with their ToS. - Free, delayed data: FRED macro lags a day or two, and yfinance occasionally throttles TSX symbols (the adapter chain falls back automatically). - Local by design: run on localhost. Tokens default to a 14-day TTL; MFA re-auth is `python mcp_login.py`. ## Quick start > The condensed version is below. If you want every step explained (what each setting does, where files go, Windows + macOS commands side by side), follow the **[full setup guide](docs/SETUP.md)** instead. > Commands below use bash (works on macOS/Linux/WSL/Git-Bash). For native Windows PowerShell equivalents, see [scripts/AUTOMATION.md](scripts/AUTOMATION.md). Replace `` with the absolute repo path. **Prerequisites:** Python 3.12+, Docker Desktop (optional, for Postgres + Redis), Claude Code CLI or Claude Desktop (Pro), Wealthsimple account (optional - required only for portfolio-aware skills). **Easiest path: install as a Claude Code plugin.** Requires [`uv`](https://docs.astral.sh/uv/getting-started/installation/) on PATH (one binary). No clone, no venv, no manual wiring: ```bash claude plugin marketplace add tusharagg1/aifolimizer claude plugin install aifolimizer@aifolimizer ``` The plugin ships all 28 skills and launches the MCP server via `uv run`, which builds the dependency env on first use. The first launch takes ~1-2 min while uv downloads wheels; if the `mcp__aifolimizer__*` tools don't show up immediately, restart Claude once (the env is cached afterward). The market-data tools work out of the box; the Wealthsimple portfolio tools stay dormant until you run `mcp_login.py` (see below). Note: plugin state (paper-trade history etc.) lives in the per-version plugin cache and resets on plugin updates, so for persistent history and the always-on scheduler, use the local clone path below. **Advanced: full local install (optional).** Most people can stop after the plugin above. Use this only for persistent paper-trade history, the always-on scheduler, or to work on the code. One command creates the venv, installs deps, seeds `backend/.env`, writes `.mcp.json` with absolute paths for your machine, registers the MCP server, and runs a health check. Idempotent (won't clobber existing config): ```bash ./setup.sh # macOS / Linux / WSL / Git-Bash powershell -ExecutionPolicy Bypass -File setup.ps1 # native Windows ``` Then edit `backend/.env` (WS creds), run `mcp_login.py`, and start `run.py` (steps 5-6 below). The manual walkthrough below is the same thing, spelled out; use it if you'd rather do each step yourself or `setup` fails. ```bash # 1. Postgres password file (required before docker compose up) mkdir -p .secrets && openssl rand -hex 24 > .secrets/pg_password.txt && chmod 600 .secrets/pg_password.txt # 2. Start infrastructure (optional - Postgres + Redis) docker compose up -d # 3. Backend install cd backend python -m venv .venv && source .venv/bin/activate pip install --upgrade pip && pip install -r requirements.txt cp ../.env.example .env && $EDITOR .env # fill WS_EMAIL, WS_PASSWORD # 4. (Optional) Claude Code permissions / hooks - skip to use defaults (more permission prompts) cd .. && cp .claude/settings.example.json .claude/settings.json $EDITOR .claude/settings.json # replace and ; delete the hooks block if you don't run sync_coordinator/obsidian_export cd backend # 5. First-time Wealthsimple login (MFA - re-run only when WS forces re-auth) python mcp_login.py # 6. Run the backend (http://127.0.0.1:8000) python run.py ``` Tokens persist to `~/.aifolimizer/ws_session.json` (mode 0600 on POSIX; NTFS-protected on Windows) so backend restarts resume without re-entering OTP. For an always-on service with scheduled-skill execution, see [scripts/AUTOMATION.md](scripts/AUTOMATION.md) (Windows/Task Scheduler today; `launchd` / `systemd` / `cron` snippets in the POSIX appendix). **Register the MCP server with Claude:** ```bash claude mcp add aifolimizer "/backend/.venv/bin/python" "/backend/mcp_server.py" ``` Or copy `.mcp.example.json` → `.mcp.json` and replace ``. For Claude Desktop, edit `claude_desktop_config.json` (see [docs/FAQ.md](docs/FAQ.md) for OS-specific paths). Restart Claude, then ask "get my profile" or run `/daily-briefing` to verify live data is flowing. **Optional:** Telegram alerts (set `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` in `.env`) and scheduled skills - full runbook in [scripts/AUTOMATION.md](scripts/AUTOMATION.md). ## Tests ```bash pytest # from repo root (testpaths configured in pyproject.toml) ``` ## Usage Skills auto-trigger on intent in Claude. Or invoke directly: ``` /daily-briefing → Morning digest: portfolio, macro, alerts, earnings /portfolio-health → Health report + rebalance plan /risk-assessment → Stress test + hedge candidates /stock-analysis NVDA → Fundamental + technical deep dive /stock-compare NVDA AAPL → Head-to-head matchup /adversarial-research VFV → Bull / bear / consensus pipeline /macro-impact → Macro briefing on live FRED data /dividend-strategy → Income blueprint /earnings-analyzer AAPL → Pre-earnings brief /earnings-postmortem AAPL → EPS beat/miss breakdown post-report /sector-rotation → Rotation signals /tax-loss-review → Canadian tax-loss harvesting (TFSA/RRSP-aware) /cash-deployment → Add-to-winners with concentration + crowding guard /pre-trade-check TSLA → Risk gate before entering a position /auto-rebalance → Drift-based rebalance recommendations /weekly-mirror → Weekly portfolio review against goals /momentum-scanner → 12-month momentum + breakout scan (scheduler-driven) /pead-tracker → Post-earnings drift tracker (scheduler-driven) /position-review → Open-position health gate (scheduler-driven) /top-trades-today → Highest-conviction tradeable ideas (scheduler-driven) /perf-optimizer → Rolling weights tuner reflection (scheduler-driven) ``` The five `(scheduler-driven)` skills run on a nightly cadence in `app/jobs/scheduler.py`; they are also invocable on demand. Sample outputs (synthetic data) live under [docs/examples/](docs/examples/). ## MCP tools (107 total - table highlights core 32; full list in `backend/mcp_server.py`) | Tool | Returns | Cache | |------|---------|-------| | `get_profile` | Account types, cash balances (PII-stripped) | session | | `get_portfolio` | Live enriched positions + summary | live | | `get_xray` | ETF exposure expansion + sector breakdown | live | | `get_concentration_warnings` | Over-allocation flags | live | | `get_tax_loss_candidates` | Underwater positions for harvesting | live | | `get_risk_metrics` | Vol, Sharpe, Sortino, VaR 95%, ES, max DD | 1h | | `get_correlation_matrix` | Pairwise correlation between top holdings | 1h | | `get_macro_snapshot` | FRED: Fed funds, 10Y, CPI, CAD/USD, BoC | 12h | | `get_fundamentals` | P/E, EPS, div yield, payout, beta, analyst target | 6h | | `get_technicals` | SMA, RSI, MACD, Bollinger, Minervini stage | 1h | | `get_earnings_calendar` | Next earnings dates, flags next-14-day names | 6h | | `get_earnings_results` | Last N quarters EPS estimate/actual/surprise | 12h | | `get_news_headlines` | Recent headlines per ticker | 30m | | `get_positioning_signals` | Crowding score, inst%, short%, headline velocity | 6h | | `get_crypto_data` | CoinGecko: price CAD, market cap, 24h/7d/30d | 5m | | `get_triggered_alerts` | Recent alert events from local log | live | | `run_alerts_now` | Evaluate alert rules vs live portfolio | live | | `backtest_portfolio` | Rule-replay: buy_hold/rsi_swing/sma_cross/crowd_fade | 1h | | `get_skill_track_record` | Backtest 13 codified-rule skills (3-5yr) | disk | | `log_recommendation` | Log rec with entry price, target, stop | live | | `score_recommendations` | Mark open recs to market, flag stops/targets hit | live | | `get_live_track_record` | Rolling 7/30/90d win-rate + P&L | live | | `snapshot_portfolio_equity` | Append today's NAV to history (idempotent) | live | | `get_alpha_attribution` | Alpha/beta vs SPY/XEQT/TSX/QQQ | live | | `get_quote_with_so … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [tusharagg1](https://github.com/tusharagg1) - **Source:** [tusharagg1/aifolimizer](https://github.com/tusharagg1/aifolimizer) - **License:** MIT 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:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **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: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-tusharagg1-aifolimizer - Seller: https://agentstack.voostack.com/s/tusharagg1 - 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%.