openmarkets

# 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)`: