Metadata-Version: 2.4
Name: filtrix-mcp
Version: 0.1.1
Summary: MCP server for Filtrix — historical trading pattern analysis for AI agents
Project-URL: Homepage, https://filtrix.net
Project-URL: Documentation, https://pypi.org/project/filtrix-mcp/
Author-email: Filtrix <support@filtrix.net>
License: MIT
License-File: LICENSE
Keywords: ai-agents,backtest,claude,filtrix,mcp,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# Filtrix MCP Server

MCP (Model Context Protocol) server that gives AI assistants access to [Filtrix](https://filtrix.net) — a historical trading pattern discovery engine with 348K+ records and 255 filters spanning 5 years of data.

## What can it do?

| Tool | Description |
|------|-------------|
| `run_backtest` | Run a historical backtest with filters. Returns sample size, win rate, average move, percentiles. |
| `screen_tickers` | Find matching historical events. Returns date, symbol, price, gap, volume. |
| `get_ticker_info` | Get ticker metadata: company name, sector, market cap, exchange, employees. |
| `list_filters` | Discover all 255 available filter columns (gap, price, float, volume, etc.). |

## Quick Start

### 1. Get an API key

Sign up at [filtrix.net](https://filtrix.net), then generate an API key in your account settings.

### 2. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "filtrix": {
      "command": "uvx",
      "args": ["filtrix-mcp"],
      "env": {
        "FILTRIX_API_KEY": "flt_your_key_here"
      }
    }
  }
}
```

Config file location:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### 3. Restart Claude Desktop

The Filtrix tools will appear automatically.

## Usage Examples

Once configured, ask Claude things like:

- *"What happens historically when a stock gaps up 30% with a float under 10M shares?"*
- *"Show me the last 20 stocks that gapped up over 50%"*
- *"Look up NVDA ticker info"*
- *"What filters are available for backtesting?"*

## Alternative: pip install

```bash
pip install filtrix-mcp
```

Then run manually:

```bash
export FILTRIX_API_KEY="flt_your_key_here"
filtrix-mcp
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `FILTRIX_API_KEY` | Yes | — | Your Filtrix API key (starts with `flt_`) |
| `FILTRIX_BASE_URL` | No | `https://filtrix.net` | API base URL |

## Rate Limits

| Tier | Daily Limit |
|------|-------------|
| Free | 50 requests |
| Pro | 1,000 requests |

Limits reset at midnight ET.

## Requirements

- Python 3.10+
- Active Filtrix account with API key
