warrant-finder-mcp

# warrant-finder-mcp MCP server for searching German exchange-listed **warrants (Optionsscheine)**. Data sources, in priority order: 1. **Börse Frankfurt** undocumented JSON API (`api.boerse-frankfurt.de/v1/search/`) — full market, salt-MD5 auth scraped from `main.<hash>.js` (technique borrowed from [joqueka/bf4py](https://github.com/joqueka/bf4py)). 2. **onvista** Derivate-Finder (`api.onvista.de/api/v1/derivatives/finder/configuration_query`) — fallback / cross-source verification. Both upstreams cover every issuer with German derivative listings (HSBC, SG, BNP, Citi, Vontobel, DZ, GS, JPM, UniCredit, Morgan Stanley, Deutsche Bank, …), so no per-issuer integration is needed. > ⚠️ Both upstream APIs are undocumented. Endpoints may change without notice; quotes are typically delayed ~15 min; redistribute the data only for personal use. ## Install ```bash uv venv .venv --python 3.13 uv pip install --python .venv/bin/python -e . ``` ## Run (stdio) ```bash .venv/bin/warrant-finder-mcp ``` ## Wire into Claude Code ```bash claude mcp add --scope user warrant-finder /absolute/path/to/.venv/bin/warrant-finder-mcp ``` Restart your terminal — every new Claude Code session will see the server. ## Tools | Tool | Purpose | | --- | --- | | `search_warrants` | Filter by underlying / issuer / Call vs Put / Hebel / strike. Returns normalized rows with bid/ask, pre-computed `spread_abs` and `spread_pct`, plus `direction_inferred` + `direction_source` when the raw name omits a Call/Put token. | | `get_warrant_details` | Full master data for a single ISIN — Greeks, implied vol, premium, currency, maturity. | | `list_issuers` | Curated issuer registry (slug → display name → onvista ID), all 12 IDs verified live. | | `search_underlyings` | Resolve a free-text underlying (e.g. "DAX") to onvista entityValue + WKN/ISIN. | ### Presentation contract The tool docstrings instruct calling agents to render results as a Markdown table that includes — at minimum — **WKN, Issuer, Direction, Strike, Leverage, Bid, Ask, Spread€, Spread%**. The Issuer column must not be dropped even when every row shares one issuer. ## Tests ```bash .venv/bin/python -m pytest tests/ -v ``` Live tests hit real upstreams to verify both clients still work and the issuer registry still resolves. MCP-protocol tests spawn the server as a subprocess and exercise the full stdio round-trip. ## Layout ``` shared/ bf_client.py Async Börse Frankfurt client (salt-signed) onvista_client.py Async onvista finder client onvista_resolver.py ISIN/free-text → onvista entityValue resolver normalize.py → unified `Derivative` model models.py Issuer registry + Derivative schema warrant_finder_mcp/server.py FastMCP server, warrant tools tests/ Live + MCP-protocol smoke tests ``` ## License **[PolyForm Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)** — free to use, copy, modify and share for any **noncommercial** purpose (personal trading, research, hobby projects, education, charities, government). **Commercial use requires a separate license — please contact the author** ([@Makki93](https://github.com/Makki93)) to discuss terms. The Börse Frankfurt client (`shared/bf_client.py`) is derived from [joqueka/bf4py](https://github.com/joqueka/bf4py) and remains usable under that project's MIT terms for the derived portions — see [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) for the full notice.