MCP 服务器

TastyScanner MCP Server

Enables AI agents to scan markets, build option strategies, track positions, and execute trades on TastyTrade via the Model Context Protocol.

README

🎯 TastyScanner MCP Server

Let Claude trade options for you on TastyTrade

Features • Quick Start • Documentation • Discord • Sponsor

</div>

🤖 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_TOKEN in .env to require Bearer token auth on all /mcp endpoints. 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 (default http://localhost:3333).
Credentials are passed via environment variables, never hardcoded.
execute_trade and adjust_order require ENABLE_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

⬆ Back to top

Made with ❤️ for the TastyTrade community