MCP Finance Server

MCP server for market data, fundamentals, screener analytics, options analytics, and Wheel strategy workflows.

This project combines:

• Interactive Brokers (real-time market connectivity)

• Yahoo Finance (broad coverage for fundamentals/history)

• Local ELT pipeline (normalized + cached tables for reliable LLM queries)

Default market for LLM-facing analytics is sweden.

Core Goals

• Stable, LLM-friendly tools with explicit defaults and predictable response envelopes.

• Reliable cached analytics from local DB first, with controlled fallbacks.

• Fast answers for practical trading questions (screener, options, Wheel).

• Clear data lineage from raw ingestion to curated analytics tables.

Why This Server vs Others

• IBKR real-time + Yahoo + local curated cache (not only direct Yahoo API reads).

• Wheel-first toolset (put selection, capacity, assignment flow, covered call continuation).

• Options with greeks + option metrics snapshots for IV and screening.

• Event risk modeling focused on Wheel impact windows.

• Local pipeline with deterministic serial jobs and MCP-friendly discovery tools.

End-to-end Example 1 (Wheel Put Selection)

1. get_wheel_put_candidates(symbol='Nordea', market='sweden', delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=10)

2. analyze_wheel_put_risk(symbol='Nordea', pct_below_spot=5.0, target_dte=7)

3. get_wheel_contract_capacity(symbol='Nordea', capital_sek=200000, market='sweden')

End-to-end Example 2 (Event Risk Window)

1. get_wheel_event_risk_window(ticker='NDA-SE.ST', market='sweden', days_ahead=14)

2. get_corporate_events(ticker='NDA-SE.ST', market='sweden')

3. get_monetary_policy_events(market='sweden')

Architecture

MCP-Finance-Server/
├── mcp_server.py                    # MCP tool registry and entrypoint
├── services/
│   ├── market_service.py            # Price lookup and symbol resolution
│   ├── option_service.py            # IB option chain + greeks
│   ├── option_screener_service.py   # Cached option metrics queries
│   ├── screener_service.py          # Stock screener + rankings
│   ├── classification_service.py    # Sector/subsector/core business/earnings
│   ├── wheel_service.py             # Wheel analytics (puts, calls, risk, stress)
│   └── job_service.py               # ELT job controls
├── dataloader/
│   ├── models.py                    # SQLAlchemy models
│   ├── seed.py                      # DB seed + default jobs
│   ├── scheduler.py                 # Cron-like job runner
│   └── scripts/                     # Extract/transform/curation scripts
└── README.md

Data Model Highlights

Key normalized/curated tables used by MCP tools:

• stocks, realtime_prices, historical_prices

• fundamentals, dividends

• stock_metrics, market_movers

• option_metrics

• option_iv_snapshots (IV history snapshots from option metrics)

• exchanges, market_indices

• sector_taxonomy, industry_taxonomy, subindustry_taxonomy

• stock_classification_snapshots, company_profiles

• raw_earnings_events, earnings_events

• raw_market_events, market_events

• stock_intelligence_snapshots (local cache for news/holders/recommendations/statements)

MCP Tool Groups

Market and Fundamentals

• get_stock_price(symbol, exchange=None, currency='USD')

• get_historical_data(symbol, duration='1 D', bar_size='1 hour', exchange=None, currency='USD')

• get_historical_data_cached(symbol, period='1y', interval='1d')

• search_symbol(query)

• get_fundamentals(symbol)

• get_dividends(symbol)

• get_dividend_history(symbol, period='2y')

• get_company_info(symbol)

• get_financial_statements(symbol)

• get_comprehensive_stock_info(symbol)

• get_exchange_info(symbol)

• yahoo_search(query)

Notes:

• get_stock_price, get_historical_data, search_symbol, get_option_chain, and get_option_greeks are DB-first (pipeline-backed snapshots).

• IB live connection remains required for account/portfolio endpoints and ingestion jobs.

IB Account and Portfolio

• get_account_summary(masked=True)

• Resource: finance://account/summary (masked by default)

• Resource: finance://portfolio/positions

Stock Screener

• get_stock_screener(market='sweden', sector=None, sort_by='perf_1d', limit=50)

• get_top_gainers(market='sweden', period='1D', limit=10)

• get_top_losers(market='sweden', period='1D', limit=10)

• get_most_active_stocks(market='sweden', period='1D', limit=10)

• get_top_dividend_payers(market='sweden', sector=None, limit=10)

• get_technical_signals(market='sweden', signal_type='oversold', limit=20)

• get_highest_rsi(market='sweden', limit=10)

• get_lowest_rsi(market='sweden', limit=10)

• get_fundamental_rankings(market='sweden', metric='market_cap', limit=10, sector=None)

Classification and Earnings

• get_companies_by_sector(market='sweden', sector=None, industry=None, subindustry=None, limit=50)

• get_company_core_business(symbol)

• get_earnings_events(symbol=None, market='sweden', upcoming_only=False, limit=20)

Options (Cached + Live)

• get_option_chain(symbol)

• get_option_greeks(symbol, last_trade_date, strike, right)

• get_option_screener(symbol=None, expiry=None, right=None, min_delta=None, max_delta=None, min_iv=None, max_iv=None, has_liquidity=True, limit=50)

• get_option_chain_snapshot(symbol, expiry=None)

• get_options_data(symbol, expiration_date=None)

Market Intelligence (Local Cache)

• get_news(symbol, limit=10)

• get_institutional_holders(symbol, limit=50)

• get_analyst_recommendations(symbol, limit=50)

• get_technical_analysis(symbol, period='1y')

• get_sector_performance(symbols)

Wheel Strategy Tools

• get_wheel_put_candidates(symbol, market='sweden', delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=10, limit=5, require_liquidity=True)

• get_wheel_put_annualized_return(symbol, market='sweden', target_dte=7)

• get_wheel_contract_capacity(symbol, capital_sek, market='sweden', strike=None, margin_requirement_pct=1.0, cash_buffer_pct=0.0, target_dte=7)

• analyze_wheel_put_risk(symbol, market='sweden', pct_below_spot=5.0, target_dte=7)

• get_wheel_assignment_plan(symbol, assignment_strike, premium_received, market='sweden')

• get_wheel_covered_call_candidates(symbol, average_cost, market='sweden', delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=21, min_upside_pct=1.0, limit=5)

• compare_wheel_premiums(symbol_a, symbol_b, market='sweden', delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=10)

• evaluate_wheel_iv(symbol, market='sweden', lookback_days=90, high_iv_threshold_percentile=70.0, target_dte=7)

• simulate_wheel_drawdown(symbol, strike, premium_received, drop_percent=10.0, market='sweden')

• compare_wheel_start_timing(symbol, market='sweden', wait_drop_percent=3.0, delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=10)

• build_wheel_multi_stock_plan(capital_sek, symbols=None, market='sweden', delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=10, margin_requirement_pct=1.0, cash_buffer_pct=0.10)

• stress_test_wheel_portfolio(capital_sek, sector_drop_percent=20.0, symbols=None, market='sweden', delta_min=0.25, delta_max=0.35, dte_min=4, dte_max=10)

Event Calendar Tools

• get_event_calendar(market='sweden', category=None, event_type=None, ticker=None, start_date=None, end_date=None, min_volatility_impact='low', limit=50)

• get_corporate_events(market='sweden', ticker=None, start_date=None, end_date=None, min_volatility_impact='low', limit=50)

• get_macro_events(market='sweden', start_date=None, end_date=None, min_volatility_impact='low', limit=50)

• get_monetary_policy_events(market='sweden', start_date=None, end_date=None, min_volatility_impact='low', limit=50)

• get_geopolitical_events(market='sweden', start_date=None, end_date=None, min_volatility_impact='low', limit=50)

• get_market_structure_events(market='sweden', start_date=None, end_date=None, min_volatility_impact='low', limit=50)

• get_wheel_event_risk_window(ticker, market='sweden', days_ahead=14, limit=100)

Local Cached DB Tools

• get_earnings_history(symbol, limit=10)

• get_earnings_calendar(symbol)

• query_local_stocks(country=None, sector=None)

• query_local_fundamentals(symbol)

Job and Pipeline Management

• list_jobs()

• get_job_logs(job_name, limit=5)

• trigger_job(job_name)

• toggle_job(job_name, active)

• get_job_status()

• run_pipeline_health_check()

Capability Discovery

• get_market_capabilities()

  • Returns grouped capabilities (methods + examples) so an LLM can answer "what can you do?" with concrete actions.

• describe_tool(tool_name)

  • Returns parameter schema (types/defaults), Pydantic JSON schema (when available), docstring summary and examples for one tool.

• help_tool(tool_name)

  • Alias for describe_tool, useful for agents that ask for help.

• get_server_health()

  • Returns health payload equivalent to /health.

• get_server_metrics(output_format='json'|'prometheus')

  • Returns metrics payload equivalent to /metrics.

Health and Metrics Resources

• Resource: finance://status

• Resource: finance://health

• Resource: finance://metrics

LLM Service Design Rules

Use these rules when adding/updating tools so other agents can depend on stable behavior.

1. Prefer intent-specific tools over mega-tools.

2. Keep safe defaults (market='sweden', low-risk limit, bounded windows).

3. Clamp limits and normalize known enum-style fields.

4. Return explicit criteria and empty_reason for zero-result queries.

5. Empty result is not a system error (success=true, data=[]).

6. Include as_of_date or as_of_datetime when data is snapshot-based.

7. Do not fabricate unavailable backend data; return uncertainty or insufficient-data states.

8. Keep response keys stable; avoid breaking renames.

9. Keep table schema stable when possible; evolve at query/service layer.

10. Protect admin endpoints with API key and strict script-path validation.

Agent Directives (MCP-friendly)

Use these directives when wiring another AI agent to this server:

1. Start by calling get_market_capabilities() for intent routing.

2. For unknown tools, call describe_tool(tool_name) before execution.

3. Prefer intent-specific tools over broad queries.

4. Always use explicit market defaults (market='sweden') unless user overrides.

5. Respect uncertainty: if backend has no data, return insufficient-data response.

6. Never infer timestamps; use meta.asof from tool responses.

7. In Yahoo-only mode (IB_ENABLED=false), avoid IB tools and fallback to local/Yahoo tools.

8. For sensitive info, keep get_account_summary(masked=True) unless user explicitly requests otherwise in trusted environment.

9. If a tool returns validation_error, fix input and retry once with corrected parameters.

10. If a source is open-circuited (circuit_open), avoid repeated retries until cooldown.

Event Modeling Rules

Use unified events in market_events with this minimum contract:

• Identification: event_id, event_type, category, subtype

• Time: event_datetime_utc, timezone, market, is_market_hours, is_pre_market, is_after_market

• Scope: ticker, sector, country, region, affected_markets

• Impact: expected_volatility_impact, systemic_risk_level, is_recurring, confidence_score

• Specific data: expected_eps, previous_eps, expected_revenue, previous_value, forecast_value, actual_value

Supported categories:

• corporate

• macro

• monetary_policy

• geopolitical

• market_structure

Stable Response Envelope

Preferred shape:

{
  "success": true,
  "data": {},
  "error": {
    "code": null,
    "message": null,
    "details": null
  },
  "meta": {
    "source": "ibkr|yahoo|local_db|pipeline|system|...",
    "asof": "2026-02-13T12:34:56.000000+00:00",
    "cache_ttl": null,
    "request_id": "uuid",
    "default_market": "sweden",
    "market_timezone": "Europe/Stockholm"
  }
}

Notes:

• The envelope is normalized in mcp_server.py (tool_endpoint decorator).

• Existing service-specific keys (count, criteria, etc.) are preserved.

Wheel Analytics Formulas

Used in wheel_service.py and exposed by MCP tools:

• Put period return (%) = (premium / strike) * 100

• Annualized return (%) = period_return * (365 / DTE)

• Cash-secured capital per contract = strike * 100

• Capacity = floor((capital * (1-cash_buffer_pct)) / (strike * 100 * margin_requirement_pct))

• Break-even (short put) = strike - premium

• Assignment probability proxy = abs(delta)

• Drawdown scenario at expiry = max(0, break_even - final_price)

Notes:

• abs(delta) is a proxy, not a true probability model.

• Timing comparison tools return scenario analysis with explicit uncertainty (no forecasts).

Data Pipeline Jobs (Key)

Major jobs in dataloader/seed.py include:

• Raw ingestion: Yahoo prices/fundamentals, IBKR prices, IBKR instruments, option metrics.

• Normalization: prices, fundamentals, classification taxonomy, company profiles.

• Curation: earnings events.

• Analytics: stock metrics, market movers, option IV snapshots, event calendar.

• Intelligence cache: news, institutional holders, analyst recommendations, financial statements snapshots.

• Loaders: stock list, reference data, dividends, historical prices, index performance.

• Validation: pipeline health check.

Seed behavior (python -m dataloader.seed):

• Idempotent sync of default jobs: missing jobs are created and existing jobs are updated (description/script/cron/timeout/tables) without duplicating rows.

• Full first load runs by default and always in serial (no parallel job execution).

• Load order is phase-based to maximize robustness:

  • MASTER: reference/tickers/raw+transform/history/dividends/earnings/classification.

  • IB: IBKR extractors/options (still serial, can be skipped).

  • COMPUTE: metrics/movers/events/intelligence snapshots.

• First-load dataset includes:

  • historical prices (5y),

  • dividends (5y),

  • earnings (10y) + curation,

  • classification normalization + company profile enrichment,

  • stock metrics + market movers,

  • normalized event calendar generation.

  • market intelligence snapshots.

• Built-in fallback: if screener baseline remains empty, it retries historical load + metrics/movers.

• Optional flags:

  • --skip-first-load: only init DB + sync jobs.

  • --skip-ib: skip IB-dependent steps during first load.

  • --warmup: deprecated alias (first load is already default).

Quick Start

5-minute onboarding (plug-and-play)

pip install -e .
python -m dataloader.seed --skip-ib
IB_ENABLED=false mcp-finance

Then point your MCP client to this server (examples below).

Docker

docker compose up -d
docker compose --profile init run seed

Local

pip install -e .
python -m dataloader.seed
mcp-finance
python -m dataloader.app

Runtime Profiles

• Yahoo-only:

  • IB_ENABLED=false

  • No IB connection attempt on startup.

  • IB tools return structured ib_disabled errors.

• IBKR + Yahoo:

  • IB_ENABLED=true (default)

  • Requires IB Gateway/TWS connectivity and market data permissions.

Environment Variables (Reference)

• IB_ENABLED:

  • true|false (default true)

• MCP_TRANSPORT:

  • sse|stdio (default sse)

• MCP_HOST:

  • default 0.0.0.0

• MCP_PORT:

  • default 8000

• DEFAULT_MARKET:

  • default sweden

• DEFAULT_MARKET_TIMEZONE:

  • default Europe/Stockholm

• MCP_TOOL_ALLOWLIST:

  • comma-separated tool names; if set, only listed tools are callable

• CIRCUIT_BREAKER_FAILURE_THRESHOLD:

  • default 4

• CIRCUIT_BREAKER_COOLDOWN_SECONDS:

  • default 45

MCP Client Config Examples

Claude Desktop

{
  "mcpServers": {
    "finance": {
      "command": "mcp-finance",
      "env": {
        "IB_ENABLED": "false",
        "DEFAULT_MARKET": "sweden",
        "DEFAULT_MARKET_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

Cursor

{
  "mcp": {
    "servers": {
      "finance": {
        "command": "mcp-finance",
        "args": [],
        "env": {
          "IB_ENABLED": "true",
          "MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}

Windsurf

{
  "mcpServers": [
    {
      "name": "finance",
      "command": "mcp-finance",
      "env": {
        "IB_ENABLED": "false"
      }
    }
  ]
}

Minimal Python Agent

import os
import subprocess

env = os.environ.copy()
env["IB_ENABLED"] = "false"
proc = subprocess.Popen(["mcp-finance"], env=env)
print("MCP Finance server PID:", proc.pid)

Security Notes

• Set DATALOADER_API_KEY for admin API endpoints.

• Keep DATALOADER_ALLOW_INSECURE=true only in local development.

• Configure CORS with DATALOADER_ALLOWED_ORIGINS.

• Optional tool allowlist: set MCP_TOOL_ALLOWLIST=get_market_capabilities,describe_tool,....

• Account summary is masked by default (get_account_summary(masked=true)).

• If running MCP over network transport (MCP_TRANSPORT=sse), keep host/firewall restricted and use API/auth controls on your MCP client gateway.

Threat Model (What this server does NOT do)

• Does not place orders.

• Does not modify positions.

• Does not submit trades.

• Does not transfer funds.

• Does not provide guaranteed forecasts.

Read-only by design: analytics, screening, events, account inspection, and pipeline control only.

Observability and Operations

• get_server_health() and resource finance://health

• get_server_metrics(output_format='json'|'prometheus') and resource finance://metrics

• Structured JSON logs per tool call (request_id, tool, source, latency, success)

• Circuit breaker by source (IBKR/Yahoo/local groups) with cooldown

• Built-in tool-level metrics: calls/failures/avg latency/source breakdown

• Rate limiter metrics exposed via IB connection runtime snapshot

Code Quality and Releases

• pre-commit hooks configured (ruff, black, isort, mypy)

• GitHub Actions CI (.github/workflows/ci.yml) running lint, type-check and tests

• Recommended release flow:

  • bump version in pyproject.toml

  • create git tag (vX.Y.Z)

  • update changelog/release notes

Operational Notes

• If screener returns empty, run:

  • Historical Prices Loader

  • Calculate Stock Metrics

  • Update Market Movers

• If Wheel IV analysis reports insufficient history, run option metrics jobs and Snapshot Option IV for multiple days.

• If option greeks are sparse, ensure IB market data permissions and option subscriptions are active.

• For macro/monetary/geopolitical events, maintain dataloader/data/manual_events.json and run Load Event Calendar.

• To refresh local news/holders/recommendations/statements cache, run Load Market Intelligence.

• To avoid duplicate manual runs, backend and frontend both protect against concurrent triggers for the same job:

  • backend returns "Job '<name>' is already queued/running" when an open run exists,

  • frontend disables the run button while request is in flight.

• Scheduler execution model is now a single-worker queue:

  • all cron/manual triggers are enqueued with status='queued',

  • only one job runs at a time globally,

  • same job is deduplicated while already queued/running.

  • on scheduler startup, orphan queued/running runs are auto-recovered to failed.

• Jobs UI uses in-app notifications/toasts and confirmation modal (no browser alert() flow).

Troubleshooting

• Error during metrics seed like operands could not be broadcast together with shapes (29,) (30,):

  • fixed by using robust return series (pct_change) in volatility calculation instead of brittle array slicing.

  • ensure you are on commit 4d0292f or newer.

• If seed fails due missing deps locally, install project dependencies first:

  • pip install -e .

License

MIT