🎯 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_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

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github		.github
examples		examples
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.combined.yml		docker-compose.combined.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🎯 TastyScanner MCP Server

🤖 What is this?

✨ Features

🎯 Why TastyScanner?

🚀 Quick Start

Option 1: Docker (Recommended)

Option 2: Node.js

Connect to Claude Desktop

Architecture

Quick Start

1. Configure credentials

2. Build and run

3. Connect to Claude Desktop

Available Tools

Tool Details

get_market_overview

get_strategies

get_positions

execute_trade

close_position

adjust_order

get_working_orders

get_watchlists

manage_watchlist

Development

Run locally (without Docker)

Test with curl

Environment Variables

Security Notes

💖 Support the Project

Sponsor Benefits

📜 License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`get_market_overview`

`get_strategies`

`get_positions`

`execute_trade`

`close_position`

`adjust_order`

`get_working_orders`

`get_watchlists`

`manage_watchlist`

Packages