# Open Markets

[![PyPI](https://img.shields.io/pypi/v/openmarkets)](https://pypi.org/project/openmarkets)
[![PyPI - Downloads](https://static.pepy.tech/badge/openmarkets)](https://pypi.org/project/openmarkets)
[![PyPI - Monthly Downloads](https://static.pepy.tech/badge/openmarkets/month)](https://pypi.org/project/openmarkets)
[![Tests](https://github.com/danchev/openmarkets/actions/workflows/checks.yaml/badge.svg)](https://github.com/danchev/openmarkets/actions/workflows/checks.yaml)
[![Tools](https://img.shields.io/badge/MCP%20Tools-127%20tools-blue)](https://github.com/danchev/openmarkets)
[![License](https://img.shields.io/badge/license-AGPLv3%2B-blue.svg)](LICENSE)

A production-grade **Model Context Protocol (MCP) server** for agentic financial data retrieval and algorithmic market analysis. Open Markets connects LLM agents directly to real-time and historical financial intelligence across equities, fixed income, commodities, currencies, derivatives, funds, crypto, macroeconomic telemetry, SEC EDGAR regulatory disclosures, and quantitative portfolio risk analytics.

<!-- mcp-name: io.github.danchev/openmarkets -->

---

## 🌟 Multi-Provider Architecture

Open Markets aggregates financial telemetry across institutional-grade data providers:
- **SEC EDGAR Direct Ingestion Engine**: Official regulatory submissions, real-time 10-K annual reports, 10-Q quarterly reports, 8-K material events, Form 4 insider transactions, and structured US-GAAP interactive XBRL disclosures with direct document links.
- **Federal Reserve Economic Data (FRED Engine)**: Comprehensive macroeconomic indicators (CPI Inflation, Core PCE, Effective Fed Funds Rate, SOFR, Nonfarm Payrolls, Unemployment, Real GDP, M2 Money Supply, Fed Balance Sheet, TIPS Breakeven Inflation, and Financial Stress).
- **Wall Street Journal (WSJ Michelangelo Engine)**: High-resolution 1-minute intraday continuous ticks (with pre/post-market), continuous commodities & futures, server-side technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands), global equity benchmark indices, and sovereign bond curves.
- **Yahoo Finance Engine**: Complete fundamental statements, real-time quotes, options chains, analyst consensus, institutional ownership, ETF compositions, and screener queries.
- **Quantitative Portfolio & Backtesting Engine**: Vectorized multi-asset Sharpe/Sortino ratios, Value-at-Risk (VaR/CVaR), correlation matrices, equal-risk-contribution allocation, constrained Markowitz Minimum Variance optimization, and SMA/RSI strategy backtesting.
- **Green Markets (Bloomberg / Dow Jones)**: Weekly North American fertilizer price index benchmark.


All network requests use modern **Chrome TLS/JA3-impersonation** (`curl_cffi`), automatic session pooling, thread-safe asynchronous concurrency, and configurable in-memory **TTL caching**.

---

## 🚀 Quick Start

### Installation with `uvx`

```bash
uvx openmarkets
```

### Usage with Claude Code

Install the Open Markets plugin from this repository:

```bash
claude plugin marketplace add danchev/openmarkets
claude plugin install openmarkets@openmarkets
```

The plugin starts `openmarkets@latest` with `uvx` and registers all MCP tools automatically.

### Usage with Cursor

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=openmarkets&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJvcGVubWFya2V0c0BsYXRlc3QiXX0=)

### Usage with Claude Desktop

Download and open the Desktop Extension for one-click installation:

[![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Download_MCPB-D97757?style=flat-square&logo=claude&logoColor=white)](https://github.com/danchev/openmarkets-mcpb/releases/latest/download/openmarkets.mcpb)

Alternatively, add Open Markets to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "openmarkets": {
      "command": "uvx",
      "args": ["openmarkets@latest"]
    }
  }
}
```

### Usage with VS Code & Cline

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "openmarkets": {
      "command": "uvx",
      "args": ["openmarkets@latest"]
    }
  }
}
```

---

## 🎯 Tool Profiles

Open Markets supports granular server profiles to tailor tool exposure to specific LLM contexts:

```bash
# Run with specific domain profile
uvx openmarkets --profile equities
uvx openmarkets --profile macro
uvx openmarkets --profile quant
uvx openmarkets --profile portfolio
uvx openmarkets --profile sec
```

| Profile | Exposed Services & Focus |
| :--- | :--- |
| **`full`** *(default)* | All 127 tools across all 17 services. |
| **`equities`** | `stock`, `financials`, `analysis`, `holdings`, `options`, `portfolio`, `screener`, `sec`. |
| **`quant`** | `stock`, `technical_analysis`, `sector_industry`, `markets`, `crypto`, `funds`, `commodities`, `fixed_income`, `forex`, `macroeconomics`, `portfolio`. |
| **`portfolio`** | Multi-asset Sharpe/Sortino, Value-at-Risk (VaR/CVaR), correlation matrices, equal-risk-contribution risk parity, Minimum Variance, rolling Beta, and strategy backtesters. |
| **`macro`** | `commodities`, `fixed_income`, `forex`, `markets`, `sector_industry`, `macroeconomics`. |
| **`sec`** | Direct SEC EDGAR submissions, 10-K, 10-Q, 8-K, Form 4, CIK search, and interactive XBRL financial statement facts. |
| **`minimal`** | Essential 36 tools across stock, financial, analyst, and screener lookups. |
| **`macroeconomics`** | US Inflation, PCE, labor markets, Fed rates, GDP, M2, liquidity, and financial stress. |
| **`commodities`** | Physical commodities, energy, metals, softs, and fertilizer indices. |
| **`fixed_income`**| Treasury yield curves and 10Y sovereign benchmark yield spreads. |
| **`forex`** | Foreign exchange rates, DXY dollar index, and currency conversions. |
| **`crypto`** | Top cryptocurrencies, historical crypto pricing, and fear & greed index proxy. |

---

## 🛠️ Complete Directory of 127 MCP Tools

Open Markets publishes **127 strictly-typed, Pydantic-validated tools** across **17 domain services**:



### 1. Stock & Equities (`StockService` — 18 tools)
- `get_fast_info(ticker)`: Fast summary with real-time price, market cap, 52-week bounds, and currency.
- `get_info(ticker)`: Exhaustive company metadata, valuation ratios, enterprise multiples, and governance.
- `get_curated_info(ticker)`: Context-efficient company fundamentals with 33 essential metrics.
- `get_history(ticker, period, interval)`: Historical OHLCV pricing with custom intervals (1m to 3mo).
- `get_dividends(ticker)`: Historical dividend payout schedule and cash amounts.
- `get_splits(ticker)`: Historical stock split ratios and execution dates.
- `get_corporate_actions(ticker)`: Combined stream of splits and dividend distributions.
- `get_news(ticker)`: Latest real-time financial news headlines and article links.
- `get_financial_summary(ticker)`: Core financial health snapshot (Revenue, Net Income, Margins, Debt).
- `get_extended_financial_summary(ticker)`: Deep financial metrics (Free Cash Flow, ROE, ROA, Quick Ratio).
- `get_risk_metrics(ticker)`: Risk indicators including Beta and institutional short interest.
- `get_dividend_summary(ticker)`: Payout ratio, trailing/forward dividend yields, and 5-year averages.
- `get_price_target(ticker)`: Analyst consensus price targets (Low, Mean, Median, High).
- `get_quick_technical_indicators(ticker)`: Lightweight 50-day & 200-day moving average levels.
- `get_valuation_history(ticker)`: Quarterly & annual historical valuation ratios (P/E, P/S, P/B, EV/EBITDA).
- `get_wsj_stock_history(ticker, timeframe, step)`: WSJ institutional price history with custom timeframes.
- `get_wsj_intraday_bars(ticker)`: Continuous 1-minute intraday tick data including pre-market and after-hours.
- `get_wsj_bollinger_bands(ticker, timeframe, window, num_std)`: Server-side calculated Bollinger Bands directly from WSJ.

### 2. Technical Analysis (`TechnicalAnalysisService` — 7 tools)
- `get_technical_indicators(ticker, period)`: Comprehensive moving averages and 52-week position metrics.
- `get_volatility_metrics(ticker, period)`: Annualized volatility, maximum daily gains/losses, win/loss day ratios.
- `get_support_resistance_levels(ticker, period)`: Identified dynamic support and resistance price floors/ceilings.
- `get_wsj_sma(ticker, window, timeframe, step)`: Server-side computed Simple Moving Average (SMA) via WSJ Michelangelo.
- `get_wsj_ema(ticker, window, timeframe, step)`: Server-side computed Exponential Moving Average (EMA).
- `get_wsj_rsi(ticker, window, timeframe, step)`: Server-side computed Relative Strength Index (RSI momentum).
- `get_wsj_macd(ticker, fast_window, slow_window, signal_window)`: Server-side computed MACD Line, Signal Line, and Histogram.

### 3. Financial Statements & SEC Filings (`FinancialsService` — 9 tools)
- `get_curated_financials(ticker)`: Context-efficient financial performance and solvency snapshot.
- `get_balance_sheet(ticker, quarterly)`: Standardized balance sheet statements (Assets, Liabilities, Equity).
- `get_income_statement(ticker, quarterly)`: Income statements (Revenues, Gross Profits, Operating Income, Net Income).
- `get_ttm_income_statement(ticker)`: Trailing Twelve Months (TTM) income statement.
- `get_ttm_cash_flow_statement(ticker)`: Trailing Twelve Months (TTM) cash flow statement.
- `get_financial_calendar(ticker)`: Upcoming earnings release dates and dividend announcement schedules.
- `get_sec_filings(ticker)`: Official EDGAR SEC filings (10-K, 10-Q, 8-K) with direct document URLs.
- `get_eps_history(ticker)`: Historical EPS consensus estimates versus reported actuals and surprise percentages.
- `get_full_financials(ticker)`: Concurrent aggregate of statements, calendar, filings, and EPS history.

### 4. Analyst Estimates & Consensus (`AnalysisService` — 8 tools)
- `get_analyst_recommendations(ticker)`: Wall Street consensus ratings breakdown (Strong Buy, Buy, Hold, Sell).
- `get_recommendation_changes(ticker)`: Recent rating upgrades and downgrades from major investment banks.
- `get_revenue_estimates(ticker)`: Forward revenue projections and quarterly growth estimates.
- `get_earnings_estimates(ticker)`: Forward EPS estimates (Quarterly & Annual).
- `get_growth_estimates(ticker)`: Multi-year earnings growth forecast comparisons.
- `get_eps_trends(ticker)`: Historical EPS revision trends (30 days, 60 days, 90 days ago).
- `get_price_targets(ticker)`: Wall Street price targets with high, low, and median projections.
- `get_full_analysis(ticker)`: Unified analyst research summary report.

### 5. Options & Derivatives (`OptionsService` — 7 tools)
- `get_option_expiration_dates(ticker)`: Available options chain expiration dates.
- `get_option_chain(ticker, expiration_date)`: Complete options chain with calls and puts.
- `get_call_options(ticker, expiration_date)`: Filtered call options with strike, bid/ask, volume, and open interest.
- `get_put_options(ticker, expiration_date)`: Filtered put options.
- `get_options_volume_analysis(ticker, expiration_date)`: Aggregate Put/Call volume and Open Interest ratios.
- `get_options_by_moneyness(ticker, expiration_date, moneyness_range)`: ITM, ATM, and OTM options filtered by moneyness.
- `get_options_skew(ticker, expiration_date)`: Volatility smile and implied volatility (IV) skew metrics.

### 6. Institutional Holdings & Insider Trades (`HoldingsService` — 6 tools)
- `get_major_holders(ticker)`: Ownership breakdown (Insiders, Institutions, Float percentages).
- `get_institutional_holdings(ticker)`: Top institutional asset managers (Vanguard, BlackRock, etc.) and shares held.
- `get_mutual_fund_holdings(ticker)`: Top mutual fund holders and portfolio portfolio position weights.
- `get_insider_purchases(ticker)`: Six-month insider purchase/sale share and transaction counts.
- `get_insider_roster_holders(ticker)`: Key company officers and board member share positions.
- `get_full_holdings(ticker)`: Unified institutional and insider ownership report.

### 7. Stock Screener (`ScreenerService` — 1 tool)
- `search_screener_matches(query, count, offset)`: Paginated discovery across Yahoo's predefined equity, ETF, and fund screens.

### 8. Sectors & Industry Analytics (`SectorIndustryService` — 13 tools)
- `get_sector_overview(sector)`: Macro sector performance and key valuation metrics.
- `get_sector_overview_for_ticker(ticker)`: Sector intelligence inferred from any ticker.
- `get_sector_top_companies(sector)`: Leading corporations by market capitalization in a sector.
- `get_sector_top_companies_for_ticker(ticker)`: Sector peers for any given ticker.
- `get_sector_top_etfs(sector)`: Benchmark ETFs representing the sector.
- `get_sector_top_mutual_funds(sector)`: Top mutual funds specialized in the sector.
- `get_sector_industries(sector)`: Sub-industry breakdown and market weightings within a sector.
- `get_sector_research_reports(sector)`: Sector research notes and macro updates.
- `get_all_industries()`: Complete directory of market industries.
- `get_industry_overview(industry)`: Industry growth, valuation, and market capitalization.
- `get_industry_top_companies(industry)`: Industry market leaders by market cap.
- `get_industry_top_growth_companies(industry)`: Fastest revenue and earnings growers in an industry.
- `get_industry_top_performing_companies(industry)`: Top price momentum leaders within an industry.

### 9. Global Markets & Volatility (`MarketsService` — 4 tools)
- `get_market_summary(market)`: Regional market overview (US, Europe, Asia).
- `get_market_status(market)`: Real-time open/closed status for major global exchanges.
- `get_global_indices()`: Live snapshot across world benchmark indices (S&P 500, Dow Jones, Nasdaq, Russell 2000, DAX 40, FTSE 100, CAC 40, Euro Stoxx 50, Nikkei 225, Hang Seng, VIX).
- `get_volatility_vix()`: Real-time quote for CBOE Volatility Index (VIX / Wall Street Fear Gauge).

### 10. Fixed Income & Sovereign Debt (`FixedIncomeService` — 3 tools)
- `get_treasury_yield_curve()`: Complete US Treasury yield curve snapshot (1M to 30Y), 2Y/10Y spread, 3M/10Y spread, and inversion status.
- `get_treasury_yield_history(maturity, timeframe, step)`: Historical yield timeseries for any Treasury tenor.
- `get_global_sovereign_yields()`: Benchmark 10-year sovereign yields and basis-point spreads vs US 10Y across 9 nations (US, Germany, UK, Japan, Canada, France, Italy, Australia, Spain).

### 11. Physical Commodities & Agriculture (`CommoditiesService` — 8 tools)
- `get_commodity_quote(symbol)`: Real-time price quote for Energy, Metals, Agriculture, Livestock, or Softs.
- `get_commodity_history(symbol, timeframe, step)`: Historical continuous futures price charts.
- `get_energy_prices()`: Multi-quote snapshot for WTI Crude, Brent, Natural Gas, Gasoline, and Heating Oil.
- `get_metals_prices()`: Multi-quote snapshot for Gold, Silver, Copper, Platinum, and Palladium.
- `get_agriculture_prices()`: Multi-quote snapshot for Wheat, Corn, Soybeans, Coffee, and Sugar.
- `get_livestock_prices()`: Live snapshot for Live Cattle, Feeder Cattle, and Lean Hogs.
- `get_softs_prices()`: Live snapshot for Coffee, Sugar, Cocoa, and Cotton.
- `get_fertilizer_price_index()`: Green Markets North American Fertilizer Price Index weekly benchmark timeseries.

### 12. Foreign Exchange (`ForexService` — 4 tools)
- `get_forex_quote(pair)`: Real-time FX exchange rate (e.g. `EURUSD`, `USDJPY`, `GBPUSD`).
- `get_forex_history(pair, timeframe, step)`: Historical FX exchange rate timeseries.
- `get_dollar_index_dxy()`: Real-time quote for the US Dollar Index (DXY).
- `get_major_currencies()`: Currency matrix across EUR, GBP, JPY, CAD, AUD, CHF, CNH.

### 13. ETFs & Mutual Funds (`FundsService` — 8 tools)
- `get_fund_info(ticker)`: ETF/Fund profile, expense ratio, AUM, category, and NAV.
- `get_fund_sector_weighting(ticker)`: Fund portfolio sector allocations and percentage weights.
- `get_fund_operations(ticker)`: Annual turnover, minimum investment, and operational parameters.
- `get_fund_overview(ticker)`: Unified fund overview with performance and fee metrics.
- `get_fund_top_holdings(ticker)`: Top underlying portfolio holdings and percentage weights.
- `get_fund_bond_holdings(ticker)`: Bond ratings breakdown, effective duration, and maturity metrics.
- `get_fund_equity_holdings(ticker)`: Equity price-to-earnings, price-to-book, and median market cap.
- `get_fund_asset_class_holdings(ticker)`: Asset class allocations (Cash, Stocks, Bonds, Real Estate).

### 14. Cryptocurrency (`CryptoService` — 4 tools)
- `get_crypto_info(symbol)`: Cryptocurrency price, market cap, 24h volume, and circulating supply.
- `get_crypto_history(symbol, period, interval)`: Historical OHLCV crypto price bars.
- `get_top_cryptocurrencies(count)`: Quotes for the configured major-cryptocurrency watchlist (not a live ranking).
- `get_crypto_fear_greed_proxy()`: Volatility and momentum proxy for crypto market sentiment.

### 15. Macroeconomics & Federal Reserve Telemetry (`MacroeconomicsService` — 9 tools)
- `get_cpi_inflation(limit)`: US Consumer Price Index (Headline CPI & Core CPI) and YoY inflation rates.
- `get_pce_inflation(limit)`: US Core Personal Consumption Expenditures (PCE) Price Index (Fed's primary 2% inflation target).
- `get_employment_indicators(limit)`: Civilian Unemployment Rate (%) and Total Nonfarm Payrolls with monthly net job additions.
- `get_interest_rates_telemetry(limit)`: Benchmark US money market rates: Effective Federal Funds Rate (EFFR) and SOFR.
- `get_gdp_growth(limit)`: Real GDP ($B chained 2017) and Nominal GDP ($B) with quarter-over-quarter annualized real growth rates.
- `get_money_supply_and_fed_balance_sheet(limit)`: US M2 Money Supply ($B) and Federal Reserve Balance Sheet Total Assets ($M).
- `get_inflation_expectations(limit)`: 5-Year and 10-Year market-implied Breakeven Inflation Rates from TIPS.
- `get_financial_stress_and_credit_spreads(limit)`: St. Louis Fed Financial Stress Index and ICE BofA US High Yield OAS credit spreads.
- `get_macroeconomic_series(series_id, limit)`: Universal query tool for any valid FRED economic series identifier (e.g. `MORTGAGE30US`, `INDPRO`, `UMCSENT`).

### 16. SEC EDGAR Filings & XBRL Disclosures (`SECService` — 9 tools)
- `get_sec_company_profile(ticker)`: Official SEC corporate registrant profile, 10-digit CIK, SIC code, business address, and incorporation metadata.
- `get_sec_recent_filings(ticker, form_type, limit)`: Recent official regulatory submissions with direct HTTPS links to primary documents on SEC EDGAR.
- `get_sec_10k_annual_filings(ticker, limit)`: Form 10-K audited annual financial reports with direct primary document links.
- `get_sec_10q_quarterly_filings(ticker, limit)`: Form 10-Q quarterly reports with unaudited financial statements.
- `get_sec_8k_material_events(ticker, limit)`: Form 8-K unscheduled material corporate event announcements (earnings releases, executive changes, M&A).
- `get_sec_insider_form4_filings(ticker, limit)`: Form 4 insider transaction reports by officers, directors, and 10%+ beneficial owners.
- `get_sec_xbrl_company_facts(ticker)`: Catalog summary of all available interactive US-GAAP XBRL disclosure concepts filed by an entity.
- `get_sec_xbrl_concept_timeseries(ticker, concept, limit)`: Multi-quarter historical timeseries for standard GAAP concepts (`REVENUES`, `NET_INCOME`, `GROSS_PROFIT`, `ASSETS`, `CASH`, `EPS`).
- `get_sec_cik_lookup(query, limit)`: Fast search directory resolving company names and tickers to official 10-digit SEC CIKs across 10,000+ public entities.

### 17. Quantitative Portfolio Risk & Strategy Backtesting (`PortfolioService` — 9 tools)
- `calculate_portfolio_risk_metrics(tickers, weights, benchmark, period, risk_free_rate)`: Multi-asset Sharpe/Sortino/Calmar ratios, Max Drawdown, Historical VaR (95%/99%), Expected Shortfall (CVaR), Beta, and Alpha.
- `calculate_asset_correlation_matrix(tickers, period)`: Pairwise Pearson correlation matrix and annualized covariance matrix across cross-asset baskets.
- `calculate_risk_parity_weights(tickers, period)`: Inverse-volatility allocation weights with actual covariance-based risk contributions.
- `calculate_minimum_variance_portfolio(tickers, period)`: Analytical long-only Markowitz Minimum Variance portfolio allocation weights.
- `calculate_rolling_beta(ticker, benchmark, window, period)`: Historical rolling window Beta sensitivity series tracking evolving market risk.
- `calculate_drawdown_series(tickers, weights, period)`: Historical underwater percentage drawdown curve and peak/trough timeline points.
- `backtest_trend_following_strategy(ticker, fast_window, slow_window, period, initial_capital)`: Moving Average Crossover (Golden Cross / Death Cross) rule-based backtester with win rate, profit factor, and equity curve.
- `backtest_mean_reversion_strategy(ticker, rsi_window, oversold_threshold, overbought_threshold, period, initial_capital)`: RSI Mean-Reversion strategy backtester with closed trades and performance breakdown.
- `calculate_factor_exposures(ticker, period)`: Multi-factor linear regression estimating systematic market loadings (SPY, QQQ, IWM, TLT, GLD) and Jensen's Alpha.



---


## 🔧 HTTP Transport & Production Deployment

Open Markets can be run as a standalone HTTP service supporting SSE streaming, Bearer token authentication, CORS, and Prometheus metrics:

```bash
# Run streamable HTTP server with auth
uvx openmarkets@latest \
  --transport http \
  --host 0.0.0.0 \
  --port 8000 \
  --http-auth-enabled \
  --http-auth-secret "your-production-secret"
```

Endpoints:
- `GET /health` — Process liveness probe.
- `GET /metrics` — Prometheus metrics (uptime, cache entries).
- `POST /mcp` — MCP streamable JSON-RPC endpoint.

---

## 📄 License

AGPLv3+ License — see [LICENSE](LICENSE) for details.