Metadata-Version: 2.5
Name: filtrix-mcp
Version: 0.6.0
Summary: MCP server for FILTRIX: historical trading pattern statistics for AI agents
Project-URL: Homepage, https://filtrix.net
Project-URL: Documentation, https://pypi.org/project/filtrix-mcp/
Author-email: Filtrix <team@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<3,>=2.3
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# FILTRIX MCP server

MCP (Model Context Protocol) server that gives AI agents access to [FILTRIX](https://filtrix.net):
historical pattern statistics over 400K+ Trade-Ideas alerts since 2019. Ask what usually happened
after a setup, list the matching events, or look up one ticker's own gap history. Save a filter set
as a run in your account and simulate an intraday entry/exit strategy on its events.

Every tool calls the FILTRIX Public API v1 with your API key. The server stores nothing.

## Tools

Two toolsets, both on by default (`FILTRIX_TOOLSETS=core,research`).

### core (read-only)

| Tool | What it returns |
|------|-----------------|
| `search_filters` | Filter columns matching a keyword: raw column name, Trade-Ideas code, description, operators. Free, no key needed. |
| `get_meta` | Outcome definitions and units, limits, daily quota per tier, data coverage. Free. |
| `get_account` | Your tier, quota used/remaining and reset time, capabilities. Free. |
| `run_backtest` | Statistics for a filter set: n, mean/median/percentiles, long/short/flat shares with their rule, monthly buckets, example events. |
| `screen_events` | Matching historical events (date, symbol, price, gap %, volume, float), plus any extra columns you ask for. |
| `get_data_coverage` | First/last event date and event counts, overall or for one ticker. |
| `get_ticker` | Ticker metadata: name, sector, market cap, exchange. |
| `get_ticker_overview` | Ticker snapshot: last close, 1d/5d/20d moves, 52-week range, TTM fundamentals. |
| `get_ticker_gap_stats` | How one ticker's own past gaps resolved (gap day and next day). |
| `get_daily_bars` | Daily OHLCV bars. |
| `get_premarket_gappers` | Today's premarket movers with the historical stats of similar gaps. Free. |

The 0.1.x names `screen_tickers`, `get_ticker_info` and `list_filters` still work and are marked
deprecated.

### research (works in your account)

| Tool | What it does |
|------|--------------|
| `save_run` | Saves a backtest as a named run (shown in the app's Context tab). Counts against the plan's saved-run limit. |
| `list_runs` | Your saved runs with their summaries. |
| `get_run` | One run: filters, summary, share link; optionally a page of its events with outcome values. |
| `share_run` / `unshare_run` | Turns the run's public read-only link on or off. |
| `delete_run` | Deletes a run permanently (marked destructive). |
| `simulate_strategy` | Simulates an entry/exit rule (open, color flip, range break; close, hold N minutes, stop/target) long or short on a run's events or on new filters: win rate, profit factor, P&L per share, holding time, trades. Uses the plan's simulation quota. |
| `get_job` / `cancel_job` | Status and result of a save or simulation job (free) / stop one. |
| `get_trade_context` | Daily bars and that day's minute bars for one event of a run. |

Saves and simulations run as background jobs. `save_run` and `simulate_strategy` wait up to
`wait_seconds` (default 20, max 50) and return the finished job, or a `job_id` to poll with `get_job`.
At most 2 jobs run at a time per account. Tools that change your account are annotated as such
(`readOnlyHint: false`; `delete_run` also `destructiveHint: true`), so clients can ask before running them.
Set `FILTRIX_TOOLSETS=core` to expose only the read-only tools.

### scanner and paper (Pro, opt-in)

Not on by default yet: they need FILTRIX to enable the live API (until then they answer "FILTRIX has not
enabled the live API yet"). Turn them on with `FILTRIX_TOOLSETS=core,research,scanner,paper`.

| Tool | What it does |
|------|--------------|
| `get_scanner_status` | Session, data freshness and whether you may use the Live Scanner. Free. |
| `search_scanner_columns` / `scan_market` | Find live columns; run filters over the live market now (trimmed rows). |
| `list_scanner_monitors` / `save_scanner_monitor` / `delete_scanner_monitor` | Your scanner windows (delete is destructive). |
| `get_scanner_matches` / `get_scanner_chart` | What your windows match now; minute and daily bars of one symbol. |
| `get_paper_status` / `get_paper_catalog` / `validate_paper_strategy` | Paper trading status (free), strategy building blocks, spec check. |
| `get_paper_account` / `list_paper_records` | Account, positions, orders, trades, journal, epochs. |
| `create_paper_account` / `update_paper_limits` / `save_paper_strategy` / `start_paper_strategy` / `pause_paper_run` / `resume_paper_run` | Paper commands. |
| `reset_paper_account` / `close_all_paper_positions` / `archive_paper_strategy` / `close_paper_run` | Destructive paper commands. |

Paper money is simulated; nothing places a real order. Each paper command sends an `Idempotency-Key`
(yours, or one derived from the tool and the exact request, so an identical retry does not act twice) and
fills in the account and draft versions from `get_paper_account` when you leave them out.

Errors come back as tool errors with the server's message, the HTTP status and a hint, e.g.
`Unknown filter column: 'price' (HTTP 400). Call search_filters to find valid column names.`

## Hosted server (no install)

FILTRIX runs this server at **`https://filtrix.net/mcp`** (Streamable HTTP).

- **claude.ai / Claude Desktop**: Settings → Connectors → Add custom connector → URL `https://filtrix.net/mcp`, then sign in with your FILTRIX account (OAuth).
- **ChatGPT** (developer mode): create a connector with that URL and OAuth.
- **Claude Code**: `claude mcp add --transport http filtrix https://filtrix.net/mcp` and authenticate with `/mcp`,
  or add `--header "X-API-Key: flt_your_key"`.
- **Cursor and other clients**: `{"url": "https://filtrix.net/mcp", "headers": {"X-API-Key": "flt_your_key"}}`.

On the consent screen you choose read-only or read and changes; connected apps are listed (and can be
disconnected) in the app under API Keys. Step-by-step: https://filtrix.net/developers

To run the HTTP server yourself: `filtrix-mcp --transport http --port 8080` with `FILTRIX_BASE_URL` (the API
it forwards to) and `FILTRIX_PUBLIC_URL` / `FILTRIX_MCP_ALLOWED_HOSTS` set. Every request must carry the
caller's own credential; the server never uses an API key of its own in this mode.

## Quick start (local, stdio)

1. Create an API key at [filtrix.net/app](https://filtrix.net/app) (API Keys tab). Keys start with `flt_`.
2. Add the server to your client.

**Claude Desktop** (`claude_desktop_config.json`; macOS `~/Library/Application Support/Claude/`,
Windows `%APPDATA%\Claude\`):

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

**Claude Code:**

```bash
claude mcp add filtrix --env FILTRIX_API_KEY=flt_your_key_here -- uvx filtrix-mcp
```

**Cursor** (`~/.cursor/mcp.json`): the same `mcpServers` block as Claude Desktop.

Or install it yourself: `pip install filtrix-mcp`, then run `filtrix-mcp` with `FILTRIX_API_KEY` set.

## Example questions

- "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%, with their relative volume."
- "How does TSLA usually trade on the day after a 10% gap down?"
- "Which premarket gappers today have the best historical follow-through?"
- "Save gap-ups over 20% under $10 as a run, then test buying the open with a 3% stop and 6% target."
- "Show me the minute chart of the worst trade from that simulation."

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `FILTRIX_API_KEY` | Yes (except `search_filters`) | | Your API key (`flt_...`) |
| `FILTRIX_BASE_URL` | No | `https://filtrix.net` | API base URL |
| `FILTRIX_TOOLSETS` | No | `core,research` | Comma list of toolsets to expose (`core`, `research`, `scanner`, `paper`) |

## Quota

| Tier | Requests per day |
|------|------------------|
| Free | 50 |
| Pro | 1,000 |

`search_filters`, `get_meta`, `get_account`, `get_premarket_gappers` and `get_job` do not count. The
day resets at midnight America/New_York; `get_account` shows the exact reset time. Saved runs and
simulations also have their own plan limits (see `get_account`).

## Requirements

Python 3.10+, a FILTRIX account with an API key.
