# MEICAgent > Multiple Entry Iron Condor (MEIC) strategy agent for 0DTE options via tastytrade and Claude Code - **Type:** MCP server - **Install:** `agentstack add mcp-joncovington-meicagent` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [joncovington](https://agentstack.voostack.com/s/joncovington) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [joncovington](https://github.com/joncovington) - **Source:** https://github.com/joncovington/MEICAgent ## Install ```sh agentstack add mcp-joncovington-meicagent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # MEICAgent An autonomous options trading agent running the **Multiple Entry Iron Condor (MEIC)** strategy on 0DTE index options. Rather than a traditional rules-only trading-bot framework, the agent itself runs the decision loop every few minutes during market hours, reading live market data, checking a stack of risk gates, and deciding whether to enter, hold, or close positions. It runs inside **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** (Anthropic's CLI coding assistant), which executes the operating instructions in `CLAUDE.md` and the skills in `.claude/commands/`. It talks to tastytrade directly via their official Python SDK (OAuth2, no middleman broker API). Live trading is gated behind an explicit config flag and defaults to dry-run. **New in this release:** a full **paper-trading system** that shadow-trades all four risk profiles against live quotes with zero capital, a dedicated paper dashboard, an unattended self-healing daemon, corrected MEIC exit rules (cash-settled positions are now left to expire, not force-closed), and automated end-of-day reports. See [What's new](#whats-new). --- ## Quick start **Prerequisites:** Python 3.11+, a tastytrade account, and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's CLI coding assistant, which runs the agent's decision loop and every `/`-command below. Install it with `npm install -g @anthropic-ai/claude-code`, then launch it from the project folder with `claude`. > Two kinds of commands appear in this guide: plain `python …` commands run in a normal terminal, and `/`-prefixed commands (like `/meic-start`) are Claude Code skills you type at the `claude` prompt. The skills just orchestrate the same underlying `python src/*.py` calls. **New to this? First, open a terminal and get the code.** You'll need [Git](https://git-scm.com/downloads) installed. Open your terminal: - **Windows** — the Git installer includes "Git Bash"; use it for every command here. - **macOS** — open **Terminal** (Applications → Utilities), or install Git via `xcode-select --install`. - **Linux** — open your terminal; install Git with your package manager (e.g. `sudo apt install git`). Then download this project and move into its folder: ```bash # 1. Download ("clone") the project, then move into the folder it creates git clone https://github.com/joncovington/MEICAgent.git cd MEICAgent ``` Every command below is run from inside that `MEICAgent` folder. On macOS/Linux, if `python`/`pip` aren't found, use `python3`/`pip3` instead. ```bash # 2. Install dependencies (tastytrade, keyring, pytz, flask from pyproject.toml) pip install -e . pip install pytest pytest-asyncio # optional — only needed to run the test suite # 3. Initialize the database python src/db.py init_db # 4. Launch Claude Code, then run the guided credential + config setup: claude ``` ``` /setup # inside Claude Code — stores credentials, creates config ``` (Prefer to configure by hand instead of `/setup`? Copy `config.example.json` to `config.json` and store credentials with `python src/tt.py secrets_set`.) > **Running on a headless Linux server** (no desktop)? There's no OS keyring there, so credential storage needs an encrypted-file or cloud-secret-manager backend — see [Headless / server credentials](docs/setup.md#headless--server-credentials-linux-without-a-desktop) in the setup guide. Then, inside Claude Code, pick a track: **Paper trading (recommended first)** — no capital, no live orders, runs all four risk profiles side by side: ``` /paper-start ``` Launches the market-data streamer, the paper dashboard at `http://localhost:5051`, and (on Windows) registers a self-healing scheduled task that evaluates every configured symbol every 2 minutes during market hours. On **macOS/Linux**, the scheduled task isn't available — instead keep the loop running in a terminal with `python src/paper_loop.py`, or wire a cron job to `python src/paper_loop.py --once` every 2 minutes. **Live / dry-run trading** — the real agent loop (defaults to dry-run until `enable_live_trading: true`): ``` /meic-start ``` Launches the streamer, the live dashboard at `http://localhost:5050`, and the agent loop. See [docs/setup.md](docs/setup.md) for the full walkthrough and [docs/paper-trading.md](docs/paper-trading.md) for the paper-trading design and graduation criteria. --- ## What's new - **Parallel-shadow paper trading** — every trading day, all four risk profiles (conservative / moderate / aggressive / very-aggressive) are evaluated deterministically against the *same* live-quote snapshot per symbol, each with its own $100,000 virtual bankroll. No capital, no live orders, apples-to-apples profile comparison. Optional SPX historical-replay mode front-loads samples from past days that actually paid. See [docs/paper-trading.md](docs/paper-trading.md). - **Corrected MEIC exit rules** — iron condors have exactly three exits: a per-side software stop, a time-based force-close **before the bell for non-cash-settled symbols only** (QQQ/IWM/equities — avoids physical assignment), and **left-to-expire cash settlement for cash-settled symbols** (SPX/XSP). There is **no profit-target exit** — that was removed as it isn't part of MEIC. Event days (FOMC, triple-witching, quarterly) still force-close everything as risk overrides. - **Two dashboards, one codebase** — the same dashboard runs against the live account (port 5050) or the paper account (port 5051, visibly badged "Paper Mode"), so you can watch both at once without confusion. - **Realistic fee modeling** — the paper engine charges tastytrade's exact broad-based-index-options fee schedule per leg (commission, clearing, ORF, per-symbol exchange fee, TAF on sells), so simulated P&L reflects real cost drag. - **Unattended, self-healing daemon** — the paper loop runs as a Windows scheduled task firing a short-lived process every 2 minutes: headless, time-gated to market hours, and persistent across sessions. It writes a deterministic end-of-day report automatically at the settlement pass. - **Automated end-of-day reports** — `/eod-report` reproduces the live report, the paper report, or both; the paper daemon also emits its report unattended each day. Bounded log rotation keeps every log file from growing without limit. --- ## Features - **Multi-symbol, one shared risk budget** — trades multiple underlyings (e.g. SPX + XSP + QQQ + IWM) concurrently in a single loop pass, sharing one account-wide buying-power/position-count budget rather than per-symbol silos. Correlation risk across symbols is not yet guarded — avoid configuring highly correlated symbols (e.g. SPX and XSP) together until that safeguard exists. - **No hardcoded contract logic** — all contract-specific parameters (instrument type, dollar multiplier, leg symbols) are read directly from the live strategy scan, so adding a new symbol needs no code changes, only a config entry. - **Settlement-aware exits** — cash-settled index options are left to expire and settled in cash; physically-settled symbols are force-closed before the bell to avoid assignment, with a missed close on a non-cash symbol escalated as an assignment-risk failure rather than routine cleanup. - **Live DXLink streaming daemon** — persistent WebSocket connection maintaining a rolling near-the-money option window per symbol (quotes, greeks, open interest, trade volume), so entry decisions and GEX calculations run off sub-second cached data instead of cold REST calls. - **Per-symbol GEX (Gamma Exposure) engine** — computes net GEX, gamma flip, call wall, and put wall live from real open interest and greeks, both from open-interest positioning and from actual traded volume. - **Adaptive per-side stop management** — call and put spreads managed independently; a stopped side doesn't force-close the untouched side. - **Opening Range Breakout (ORB) sub-strategy** — a directional debit-spread complement to the core IC strategy, capturing the 9:30–9:35 ET range and trading breakouts. ORB keeps its own profit target and stop, distinct from the iron-condor exit rules. - **Fee-aware credit floors** — rejects entries where estimated fees would eat most/all of the collected premium, using each symbol's own historical fee data once enough trades exist. - **Full audit trail** — every loop iteration, entry, rejection reason, and stop adjustment is logged with reasoning, plus an automatically-written end-of-day narrative report. ## Simplified entry gate logic All of the following must pass — any one failure blocks the trade: 1. **Time window** — no entries before 10:00 ET or after 14:30 ET. At end of day, non-cash-settled positions are force-closed before the bell; cash-settled positions are left to expire and settle in cash. Event days force-close everything. 2. **IV rank floor** — skip if IV rank is too low (insufficient premium to justify gamma risk). 3. **Late-entry bias** — on borderline-IV days, wait until noon rather than accept thin morning credit for the same directional exposure. 4. **Strike selection** — target a VIX-banded short-strike delta, then apply hard floors on top: minimum distance (%) from spot for both the short call and short put, and a ceiling on the actual call delta regardless of what the delta-target scan picked. 5. **Credit floors** — two independent checks: credit as a % of spread width, and a fee-adjusted floor (the credit must clear estimated fees by a real, width-aware margin). Both are width- and IV-aware, so narrow low-credit setups where fees would consume the premium are rejected. 6. **GEX regime gate** — no new iron condors when the symbol is in a *negative* gamma regime (dealers short gamma = trending/volatile conditions where mean-reversion strategies like MEIC underperform); ORB entries are exempt since they want that regime. 7. **Account-wide caps** — max concurrent condors and max daily entries are shared across every traded symbol, not per-symbol. 8. **Event calendars** — hard blackouts/tighter rules around FOMC announcements, quarterly expiry, and triple witching. ## Risk Profiles Switch entry-gate thresholds with a single command instead of hand-editing `config.json`. A **risk profile** bundles IV-rank floors, credit minimums, delta limits, stop triggers, and position caps — each preset offsets its gate relaxations with compensating constraints (fewer concurrent ICs, tighter stops) so you're reallocating risk, not just adding it. | Profile | What it does | Trade-off | |---|---|---| | **conservative** (default) | Strict IV-rank (≥30%) and credit floors, wide OTM buffers, latest entry time (12:00 PM) | Fewest trades (~1–2/day), highest per-trade safety margin | | **moderate** | Slightly relax IV-rank (≥22%) and credit floors, enter earlier (11:00 AM) | ~1 more trade/day, thinner credit cushion but offset by tighter 93% stop | | **aggressive** | Tier 1 + accept closer-to-money strikes (delta 0.22, OTM tighter); cap 3 concurrent ICs instead of 4 | ~2–3 more trades/week, each one riskier but position cap and 90% stop limit total exposure | | **very-aggressive** | Tier 2 + trade through higher-VIX (≤30) and trending (ATR ≤40) conditions; cap 2 concurrent ICs, stop at 85% | Most trades (~3–5 more/week on active weeks), each with high gamma/pin risk; only for deliberate short experiments | Use `/set-risk-profile ` to switch (backed up automatically, takes effect on next loop). The paper-trading system runs **all four profiles at once** so you can compare them on identical market days before committing to one. Start at **moderate** after 2–4 weeks if conservative rejects 40%+ of entries. See [docs/risk-profiles.md](docs/risk-profiles.md) for the full rationale, decision tree, and when to escalate. ## Paper trading Before risking capital, run the parallel-shadow paper engine to build a performance record: ``` /paper-start # streamer + paper dashboard + unattended daemon /paper-report # weekly (or custom-range) profile comparison python src/paper_loop.py --eod-report # deterministic end-of-day report on demand python src/paper_loop.py --status # daemon/task status + open-position count python src/paper_loop.py --uninstall-task # stop the unattended session ``` Every 2 minutes during market hours, the engine takes one live-quote snapshot per symbol and runs all four risk profiles against it deterministically — synthetic fills at natural bid, each profile on its own $100,000 virtual bankroll, tastytrade's exact fee schedule applied per leg. Writes go only to `data/paper_trades.db`; the live account and `data/meic_trades.db` are never touched, and no live order is ever submitted (paper mode is not gated by `enable_live_trading`). A pre-registered **graduation gate** (≥30 filled ICs, positive expectancy, ≥65% win rate, profit factor 1.3–4.0, bounded drawdown and worst day) decides when a profile has earned live capital. See [docs/paper-trading.md](docs/paper-trading.md) for the full design, the SPX historical-replay accelerator, and the known limitations of a frictionless paper model. ## Dashboard The same local web dashboard (auto-refreshing) runs in two modes: - **Live mode** (`/dashboard`, port 5050) — your real tastytrade account - **Paper mode** (`/paper-dashboard`, port 5051) — the paper account, visibly badged "Paper Mode — Simulated" so it can never be mistaken for real data Both can run at once. Views: - **Performance view** — P&L by day/week/month/all-time, equity and underwater curves, win-rate/profit-factor/expectancy trends, and risk-adjusted tiles (Sharpe/Sortino/Calmar/recovery factor); filterable by symbol, and by risk profile in paper mode - **Today view** — live open positions with per-spread credits and per-side stop badges, plus a multi-period stats grid - **GEX view** — horizontal by-strike gamma exposure profile (classic dealer-positioning chart style) with call wall / put wall / zero-gamma reference lines and a live spot-price trail; toggle OI-based vs volume-based GEX side by side - **IV Skew & Volume tabs** — call/put IV curve and open-interest/volume-by-strike from the same live data - **Live log tail** — streaming agent log with level filtering, so you can watch the reasoning in real time Everything runs locally against your own tastytrade account — no cloud dependency for trade execution. --- ## Documentation - [Setup](docs/setup.md) — installation, configuration, database init, going live - [Operating](docs/operating.md) — starting the loop, status, dashboard, EOD report, logs - [Strategy](docs/strategy.md) — MEIC structure, wing width selection, stops, exit rules, EOD settlement handling - [Paper trading](docs/paper-trading.md) — the parallel-shadow engine, fee model, historical replay, graduation gate, known limitations - [Risk Profiles](docs/risk-profiles.md) — trade-off tiers for entry-gate thresholds, when to switch, full rationale --- ## Project structure ``` MEICAgent/ ├── CLAUDE.md # Agent operational brain (loaded every loop iteration) ├── config.example.json # Config template — copy to config.json ├── config.risk.json # Risk-profile presets (conservative → very-aggressive) ├── src/ │ ├── tt.py # tastytrade CLI — get_quote, get_strategies, execute_trade, etc. │ ├── streamer.py # Persistent DXLink streaming daemon (live quotes/greeks/OI/volume) │ ├── session.py # OAuth2 session management │ ├── credentials.py # OS-keyring credential storage │ ├── db.py # SQLite CLI helper (live + paper databases) │ ├── notify.py # Structured log CLI helper │ ├── paper.py # Deterministic parallel-shadow paper engine (all 4 profiles) │ ├── paper_loop.py # Unattended paper daemon / scheduled-task runner + EOD report │ … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [joncovington](https://github.com/joncovington) - **Source:** [joncovington/MEICAgent](https://github.com/joncovington/MEICAgent) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-joncovington-meicagent - Seller: https://agentstack.voostack.com/s/joncovington - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.