Metadata-Version: 2.4
Name: finviz-market-mcp
Version: 0.1.1
Summary: MCP server exposing Finviz market data via finvizfinance
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: finvizfinance>=1.0.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.16.5
Dynamic: license-file

# finviz-market-mcp

MCP server exposing [Finviz](https://finviz.com) market data via the [finvizfinance](https://github.com/lit26/finvizfinance) library.

Provides 23 tools for stock fundamentals, analyst ratings, screener, insider trading, sector analysis, forex, crypto, futures, and calendars.

## Installation

### Using uvx (recommended)

No installation needed. Run directly:

```bash
uvx finviz-market-mcp
```

### Using pip

```bash
pip install finviz-market-mcp
```

### From source

```bash
pip install -e .
```

## Usage

### Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "finviz": {
      "command": "uvx",
      "args": ["finviz-market-mcp"]
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "finviz": {
      "command": "uvx",
      "args": ["finviz-market-mcp"]
    }
  }
}
```

## Tools Reference

### Quote / Single Ticker (11 tools)

| Tool | Description |
|------|-------------|
| `get_stock_fundamentals(ticker)` | 70+ fundamental fields: P/E, EPS, Recom, Target Price, Market Cap, etc. |
| `get_stock_description(ticker)` | Company description text |
| `get_stock_ratings(ticker)` | Analyst ratings (upgrades, downgrades, initiations) |
| `get_stock_news(ticker, max_rows)` | Ticker-specific news articles |
| `get_stock_insider_trades(ticker, max_rows)` | Insider trading for a specific stock |
| `get_stock_snapshot(ticker)` | Composite: fundamentals + description + ratings + news + peers |
| `get_stock_peers(ticker)` | Peer ticker symbols |
| `get_stock_etf_holders(ticker)` | ETFs holding this stock |
| `get_stock_chart_url(ticker, timeframe, chart_type)` | Finviz chart URL |
| `get_financial_statements(ticker, statement, timeframe)` | Income/Balance/CashFlow statements |
| `get_current_price(ticker)` | Current stock price |

### Screener (3 tools)

| Tool | Description |
|------|-------------|
| `screen_stocks(signal, filters, ticker, view, order, limit, ascend)` | Full screener with 33 signals + filters across 6 views |
| `screen_tickers(signal, filters, ticker, order, limit, ascend)` | Lightweight screener returning ticker symbols only |
| `get_screener_filters(filter_name)` | Discover available filters, signals, and sort orders |

### Market News (1 tool)

| Tool | Description |
|------|-------------|
| `get_market_news(max_rows)` | General market news and blogs |

### Insider Trading (1 tool)

| Tool | Description |
|------|-------------|
| `get_insider_trades(option, max_rows)` | Market-wide insider trading activity |

### Group / Sector Analysis (2 tools)

| Tool | Description |
|------|-------------|
| `get_group_overview(group, view, order)` | Sector/Industry/Country group analysis |
| `get_group_filters()` | Discover available groups and sort orders |

### Macro / Multi-Asset (3 tools)

| Tool | Description |
|------|-------------|
| `get_forex_performance(change)` | Forex pairs performance |
| `get_crypto_performance()` | Cryptocurrency performance |
| `get_futures_performance(timeframe)` | Futures performance |

### Calendars (2 tools)

| Tool | Description |
|------|-------------|
| `get_earnings_calendar(period, mode)` | Earnings calendar by day |
| `get_economic_calendar()` | Economic releases calendar |

## Publishing to PyPI

```bash
uv build
uv publish
```

## License

MIT
