Metadata-Version: 2.4
Name: financial-mcp-server
Version: 0.1.7
Summary: MCP server for AI-powered stock market intelligence
Author-email: Arnav Bhat <arnav.cal@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/arnavbhat1/financial-mcp
Project-URL: Repository, https://github.com/arnavbhat1/financial-mcp
Project-URL: Issues, https://github.com/arnavbhat1/financial-mcp/issues
Keywords: mcp,finance,stock,trading,paper-trading,yfinance,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: yfinance>=0.2.31
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pytrends>=4.9.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# financial-mcp-server

[![PyPI Downloads](https://static.pepy.tech/personalized-badge/financial-mcp-server?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/financial-mcp-server)

MCP server for AI-powered stock market intelligence. 33 tools for any MCP-compatible AI agent.

No API keys required (FRED key optional). Market data from yfinance, SEC EDGAR, CFTC, Treasury.gov, and Google Trends.

## Tools

### Analysis & Scoring
| Tool | What it does |
|------|-------------|
| `analyze_ticker` | Full analysis: fundamentals, momentum, composite score |
| `scan_universe` | Rank tickers by composite score |
| `score_ticker` | Composite score (0-100) with breakdown |
| `get_fundamentals` | PE, EV/EBITDA, P/B, dividend yield, market cap |
| `get_momentum` | 30d/90d momentum, volatility, relative strength |
| `get_price` | Current price |

### SEC EDGAR
| Tool | What it does |
|------|-------------|
| `get_sec_filings` | 10-K, 10-Q, 8-K filings for any public company |
| `get_insider_trades` | Insider buys/sells (Forms 3/4/5) |
| `search_sec_filings` | Full-text search across all SEC filings |

### Macro & Economic
| Tool | What it does |
|------|-------------|
| `get_economic_indicator` | Any FRED series (GDP, CPI, unemployment, etc.) |
| `get_yield_curve` | Treasury yield curve with inversion detection |
| `get_economic_snapshot` | Key indicators at a glance |
| `get_treasury_rates` | Average Treasury interest rates |
| `get_treasury_yield_curve` | Daily yield curve data (1mo-30yr) |
| `get_treasury_auctions` | Recent auction results |

### Futures & Positioning
| Tool | What it does |
|------|-------------|
| `get_futures_positioning` | CFTC COT data for any commodity/index |
| `get_smart_money_signal` | Bullish/bearish signal from commercial hedgers |

### Sentiment & Trends
| Tool | What it does |
|------|-------------|
| `get_search_trends` | Google Trends interest over time |
| `get_trending_searches` | Currently trending searches |

### Market Intelligence
| Tool | What it does |
|------|-------------|
| `detect_market_regime` | BULL / BEAR / SIDEWAYS / HIGH_VOLATILITY / CRASH |
| `get_regime_history` | Monthly regime classification |
| `get_vix_analysis` | VIX level, percentile, fear signal |
| `scan_anomalies` | Volume spikes, gaps, 52w extremes, divergences |
| `scan_volume_leaders` | Unusual volume detection |
| `scan_gap_movers` | Significant gap ups/downs at open |

### Portfolio & Paper Trading
| Tool | What it does |
|------|-------------|
| `create_portfolio` | Start a paper portfolio (capital, risk profile, horizon) |
| `analyze_portfolio` | Holdings, allocations, performance, and risk summary |
| `get_holdings` | Current positions with values |
| `get_trades` | Trade history (filter by status) |
| `execute_buy` | Buy shares at the current price |
| `execute_sell` | Sell shares at the current price |
| `run_rebalance` | Score a universe and execute buy/sell signals |
| `check_risk` | Stress score, scenario drawdowns, concentration |

Paper-trading state is stored in a local SQLite DB (see `FINANCIAL_MCP_DB_PATH` below).

## Install

**pip:**
```bash
pip install financial-mcp-server
financial-mcp
```

**uvx (no install):**
```bash
uvx financial-mcp-server
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "financial-mcp": {
      "command": "uvx",
      "args": ["financial-mcp-server"]
    }
  }
}
```

**Claude Code:**
```bash
claude mcp add financial-mcp -- uvx financial-mcp-server
```

## Configuration

The server speaks **stdio** by default (what `uvx`, Claude Desktop, and Claude Code
use). For a network/SSE server instead, run `financial-mcp --transport sse` (or set
`FINANCIAL_MCP_TRANSPORT=sse`).

Optional environment variables:

| Variable | Purpose | Default |
|----------|---------|---------|
| `FRED_API_KEY` | Unlocks FRED macro tools ([free key](https://fred.stlouisfed.org/docs/api/api_key.html)) | unset (FRED tools limited) |
| `FINANCIAL_MCP_DB_PATH` | Where paper-trading SQLite data lives | `~/.financial-mcp/financial_mcp.db` |
| `FINANCIAL_MCP_CONFIG` | Path to a custom `config.yaml` | bundled defaults |
| `FINANCIAL_MCP_TRANSPORT` | `stdio` or `sse` | `stdio` |

No config file is required — sensible defaults are built in.

## License

MIT
