TastyScanner-MCP-Server
technet365/TastyScanner-MCP-Server
MCP Server for TastyTrade - Let Claude/GPT trade options for you. Iron Condor strategy builder, market scanner, position tracking.
Instalação
npx convez-ai technet365/TastyScanner-MCP-Server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
🎯 TastyScanner MCP Server
Let Claude trade options for you on TastyTrade
Features • Quick Start • Documentation • Discord • Sponsor
🤖 What is this?
TastyScanner MCP Server connects Claude, GPT, or any AI agent to your TastyTrade account via the Model Context Protocol.
Ask your AI assistant to:
- "Scan the market for high IVR stocks"
- "Build an Iron Condor on SPY with 30-45 DTE"
- "Show my positions and P&L"
- "Close my AAPL position at 50% profit"
✨ Features
| Feature | Description |
|---|---|
| 🔍 Market Scanner | Scan symbols for IVR, IV, beta, price, earnings dates |
| 🏗️ Strategy Builder | Auto-construct Iron Condors with POP, R:R, Greeks |
| 📊 Position Tracking | Real-time P&L, Greeks, days to expiration |
| ⚡ Trade Execution | Place and close multi-leg options orders |
| 🔒 Safety First | Live trading disabled by default, sandbox support |
| 🐳 Docker Ready | One-command deployment |
🎯 Why TastyScanner?
| TastyScanner | Other MCP Servers | |
|---|---|---|
| Strategy Builder (Iron Condor auto-construction) | ✅ | ❌ |
| POP Calculation (Probability of Profit) | ✅ | ❌ |
| TypeScript (Node.js ecosystem) | ✅ | Python only |
| Docker-first | ✅ | Manual setup |
| Watchlist Management | ✅ | ❌ |
🚀 Quick Start
Option 1: Docker (Recommended)
# Clone
git clone https://github.com/technet365/TastyScanner-MCP-Server.git
cd TastyScanner-MCP-Server
# Configure
cp .env.example .env
# Edit .env with your TastyTrade OAuth credentials
# Run
docker compose up -d
# Verify
curl http://localhost:7698/health
Option 2: Node.js
npm install
cp .env.example .env
npm run build
npm start
Connect to Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"tastytrade": {
"url": "http://localhost:7698/mcp"
}
}
}
Architecture
┌────────────────────┐ ┌─────────────────────┐
│ Claude / GPT / │ │ TastyScanner-MCP │
│ Any AI Agent │── MCP ──│ (port 7698) │
└────────────────────┘ HTTP └──────────┬──────────┘
│
@tastytrade/api
│
┌──────────▼──────────┐
│ TastyTrade API │
│ (WebSocket + REST) │
└─────────────────────┘
The MCP server connects to TastyTrade using the official @tastytrade/api SDK
with OAuth authentication (client credentials + refresh token).
Quick Start
1. Configure credentials
cp .env.example .env
# Edit .env with your TastyTrade OAuth credentials
2. Build and run
docker compose build
docker compose up -d
curl http://localhost:7698/health
3. Connect to Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"tastytrade": {
"url": "http://localhost:7698/mcp"
}
}
}
Available Tools
| Tool | Description |
|---|---|
get_market_overview | Scan symbols for IVR, IV, beta, price, earnings |
get_strategies | Build Iron Condor setups for a symbol |
get_positions | List current open positions with P&L |
execute_trade | Place an options order (⚠️ real money) |
close_position | Close an existing position |
adjust_order | Adjust working order price for better fill |
get_working_orders | List pending/unfilled orders |
get_account_info | Account balance and buying power |
get_connection_status | Check TastyTrade connection health |
get_watchlists | List personal and platform watchlists |
manage_watchlist | Create, add to, remove from, or delete watchlists |
Tool Details
get_market_overview
Params: symbols?[], min_ivr?, min_price?, max_price?
Returns: [{symbol, price, ivr, iv, beta, earnings_date}] sorted by IVR desc
get_strategies
Params: symbol, min_dte?, max_dte?, min_delta?, max_delta?, wings?[], max_results?
Returns: [{strategy_name, expiry_date, dte, legs[], credit, max_profit, max_loss, rr_ratio, pop, theta, delta, wings, bpe}]
get_positions
Params: (none)
Returns: [{position_id, symbol, strategy, legs[], entry_credit, current_value, pnl, pnl_percent, dte, opened_at}]
execute_trade
Params: symbol, legs[{action, symbol, quantity}], limit_price, price_effect, time_in_force?, order_type?
Returns: {order_id, status, message}
⚠️ This places REAL orders with REAL money.
close_position
Params: position_id, reason, limit_price?
Returns: {order_id, status, pnl_realized, message}
adjust_order
Params: order_id, adjustment ('improve_fill' | 'custom'), custom_price?
Returns: {order_id, old_price, new_price, status, message}
⚠️ Requires ENABLE_LIVE_TRADING=true
get_working_orders
Params: (none)
Returns: [{order_id, symbol, status, price, price_effect, legs[]}]
get_watchlists
Params: include_public? (default: true)
Returns: {personal: [{name, symbols[]}], platform: [{name, symbol_count}]}
manage_watchlist
Params: action ('create' | 'add' | 'remove' | 'delete'), name, symbols?[]
Returns: {success, message}
Development
Run locally (without Docker)
cd tastyscanner-mcp
npm install
# Copy env template and fill in credentials
cp .env.example .env
# Edit .env with your OAuth credentials
# Run with hot-reload
npm run dev
# Or build and run
npm run build
npm start
Test with curl
# Initialize MCP session (add -H "Authorization: Bearer <token>" if MCP_AUTH_TOKEN is set)
curl -X POST http://localhost:7698/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "test", "version": "1.0.0"}
}
}'
# Call a tool (use session-id from init response)
curl -X POST http://localhost:7698/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "mcp-session-id: <session-id>" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_connection_status",
"arguments": {}
}
}'
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
TASTY_CLIENT_ID | Yes | — | TastyTrade OAuth Client ID |
TASTY_CLIENT_SECRET | Yes | — | TastyTrade OAuth Client Secret |
TASTY_REFRESH_TOKEN | Yes | — | TastyTrade OAuth Refresh Token |
TASTY_ACCOUNT | No | auto | Account number (auto-detects first) |
TASTY_PRODUCTION | No | true | true = production, false = sandbox |
MCP_PORT | No | 7698 | HTTP server port |
MCP_AUTH_TOKEN | No | — | Bearer token for endpoint auth. If set, all /mcp requests require Authorization: Bearer <token> |
LOG_LEVEL | No | info | debug, info, warn, error |
ENABLE_LIVE_TRADING | No | false | Set true to allow execute_trade and adjust_order |
Security Notes
- Authentication: Set
MCP_AUTH_TOKENin.envto require Bearer token auth on all/mcpendpoints. Without it, the server is open (backwards compatible but not recommended for production). - Rate limiting: 120 requests/minute per IP on MCP endpoints.
- CORS: Restricted to
MCP_CORS_ORIGIN(defaulthttp://localhost:3333). - Credentials are passed via environment variables, never hardcoded.
execute_tradeandadjust_orderrequireENABLE_LIVE_TRADING=true— disabled by default.- Session IDs use
crypto.randomUUID()(cryptographically secure). - Account numbers are masked in logs (last 4 digits only).
- Do not expose port 7698 to the internet without auth enabled.
💖 Support the Project
If TastyScanner MCP Server saves you time or helps you trade better, consider supporting its development:
Sponsor Benefits
| Tier | Benefits |
|---|---|
| ☕ $5/mo | Support development, name in README |
| 🥈 $15/mo | Early access to new features, priority support |
| 🥇 $50/mo | Direct input on roadmap, 1:1 onboarding call |
📜 License
MIT © 2024-2025 technet365
Made with ❤️ for the TastyTrade community