tastytrade-mcp

TastyTrade MCP Server

A Model Context Protocol (MCP) server that connects your TastyTrade trading account to AI assistants like Claude Desktop and ChatGPT for conversational trading and portfolio management.

🌟 Features

✅ Production-Ready OAuth Trading (v1.4.0)

• 🎉 Full OAuth Support - Production trading via OAuth2 authentication
• 📈 All Instrument Types - Stocks, Options, Futures, Crypto
• ✅ Tested & Verified - Real orders placed and cancelled successfully
• 🔄 Universal Order Handler - Same code works in sandbox and production

Multi-LLM Support

• 🤖 Claude Desktop - Native MCP integration via stdio
• 💬 ChatGPT - HTTP MCP Bridge for Developer Mode
• 🔄 Universal Deployment - Works on any cloud platform

Trading Capabilities

• 📊 Real-time Market Data - Live quotes, options chains, market search
• 💼 Portfolio Management - Account positions, balances, order history
• 🔍 Symbol Search - Find stocks, options, and other instruments
• 🔒 Security First - Two-step trading confirmation, audit logging
• 💰 Full Order Support - Limit, Market, Stop, Stop Limit orders

API Limitations

⚠️ Important: The TastyTrade API has certain limitations. The following features are NOT available:

• Options Greeks - Delta, Gamma, Theta, etc. are not provided by the API
• Historical Price Data - No historical bars/candles endpoint available
• These tools have been removed to avoid misleading functionality

Enterprise-Grade Security

• 🔐 Secure Authentication - Your credentials never exposed to AI
• 📝 Comprehensive Audit Trail - All operations logged for compliance
• 🚫 LLM Safety - Trading requires explicit user confirmation

🚀 Quick Start

Prerequisites

• TastyTrade trading account (production or sandbox)
• Python 3.8+ with pipx installed

Install & Setup

# 1. Install the package
pipx install tastytrade-mcp

# 2. Run interactive setup
tastytrade-mcp setup

# 3. Start MCP server for Claude Desktop
tastytrade-mcp local

⚙️ Interactive Setup

The setup wizard will guide you through two authentication modes:

Simple Mode (Recommended for new users)

• Username/password authentication
• Credentials stored in .env file
• Quick setup, no database required

Database Mode (Advanced)

• OAuth2 with encrypted token storage
• Persistent authentication sessions
• SQLite database with encrypted tokens

OAuth2 Personal Grant Setup for Database Mode

Database mode uses OAuth2 personal grants for secure, encrypted token storage. This is perfect for personal use and self-hosted deployments.

Step 1: Create Your OAuth Application

• Go to https://my.tastytrade.com
• Navigate to: Manage → My Profile → API → OAuth Applications
• Click + New OAuth Client
• Fill out the form:
  • Client Name: TastyTrade MCP Server (or your preferred name)
  • Redirect URI: http://localhost:8000/callback (required but not used for personal grants)
  • Scopes: Select read and trade
• Click Create
• IMPORTANT: Copy and securely save:
  • ✅ Client ID
  • ✅ Client Secret (shown only once!)

Step 2: Generate Personal Grant

• On the OAuth Applications page, click Manage next to your application
• Click Create Grant
• IMPORTANT: Copy and securely save your Refresh Token (shown only once!)

Step 3: Run Database Setup

tastytrade-mcp setup --mode database

The setup wizard will prompt you for:

• Client ID (from Step 1)
• Client Secret (from Step 1)
• Refresh Token (from Step 2)

Security Features:

• ✅ Tokens encrypted and stored in local SQLite database
• ✅ Automatic access token refresh (every 15 minutes)
• ✅ Long-lived refresh token (never expires)
• ✅ No browser redirects - fully local setup

Important Security Notes:

• ⚠️ Keep Client Secret and Refresh Token safe - they're like passwords
• ⚠️ Never commit them to git or share publicly
• ⚠️ If compromised, delete the grant on my.tastytrade.com and create a new one
• ⚠️ Store them in environment variables or secure password manager

Setup Commands

# Interactive setup wizard
tastytrade-mcp setup

# Simple mode setup
tastytrade-mcp setup --mode simple

# Database mode setup
tastytrade-mcp setup --mode database

# Check current status
tastytrade-mcp status

# Test your connection
tastytrade-mcp test

# Clean all config/database files
tastytrade-mcp clean

⚠️ Important: Use your real TastyTrade account credentials. This connects to your actual trading account.

Security Features

• Credentials never exposed to AI assistants
• All tokens encrypted using Fernet symmetric encryption
• Two-step trading confirmation required
• Comprehensive audit logging

📱 Usage

For Claude Desktop

tastytrade-mcp local

Then restart Claude Desktop and ask: "Show my TastyTrade positions"

Available CLI Commands

tastytrade-mcp setup     # Interactive setup wizard
tastytrade-mcp local     # Start MCP server for Claude Desktop
tastytrade-mcp status    # Show configuration status
tastytrade-mcp test      # Test API connections
tastytrade-mcp clean     # Remove all config/database files
tastytrade-mcp --help    # Show all available commands

🌐 Claude Desktop Integration

Once you've run tastytrade-mcp local, the MCP server is ready for Claude Desktop:

• Restart Claude Desktop - Close and reopen the application
• Verify Connection - Claude should detect the MCP server automatically
• Start Trading - Ask Claude about your positions, balances, or market data

Example Questions for Claude:

"Show me my current TastyTrade positions"
"What's my account balance?"
"Get a quote for AAPL"
"Search for AI-related stocks"
"Show me my recent orders"

🛠️ Available Tools

Account Management

• accounts - List all TastyTrade accounts
• balances - Get account balance information
• positions - View current positions

Market Data

• search_symbols - Search stocks, ETFs, and other instruments
• quote - Get real-time market quotes
• search_options - Find options chains with filtering

Security & Audit

• audit_log - View trading activity audit trail
• security_status - Check authentication and encryption status

📊 Management Commands

# Check current installation status
tastytrade-mcp status

# Test API connection and authentication
tastytrade-mcp test

# Remove all configuration and database files
tastytrade-mcp clean

# Show all available commands
tastytrade-mcp --help

🔧 Manual Installation (Advanced)

If you prefer manual setup:

git clone <repository-url>
cd Tasty_MCP
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Create .env file with your credentials
echo "TASTYTRADE_USERNAME=[e-mail]" > .env
echo "TASTYTRADE_PASSWORD=your_password" >> .env
echo "TASTYTRADE_USE_PRODUCTION=true" >> .env

# Start server
python tastytrade_unified_server.py

🔒 Security Best Practices

• Never commit credentials - Always use .env files
• Use production accounts - Connect to your real TastyTrade account
• Monitor audit logs - Review all trading activity
• Secure your deployment - Use HTTPS and authentication tokens
• Regular updates - Keep the server updated for security patches

⚠️ Important Disclaimers

• Real Trading: This connects to your actual TastyTrade account with real money
• User Responsibility: All trades require your explicit confirmation
• No Financial Advice: This is a technical tool, not investment advice
• Security: Keep your credentials secure and use HTTPS in production

📚 Usage Examples

Getting Portfolio Information

"Show me my current positions and account balances"
"What are my open orders?"
"Get real-time quotes for NVDA, TSLA, and AAPL"

Real-Time Market Data

"Get live quotes for my stock holdings"
"Stream real-time data for AAPL for 30 seconds"
"Show me the current market price of Bitcoin futures"

Options Trading Workflow

# Step 1: Get your current option positions
"Show me all my current option positions"

# Step 2: Get real-time pricing (use exact symbols from positions)
"Get real-time quotes for these symbols: AMD  251121P00165000, NVDA  251121C00240000"

# Step 3: Analyze options strategies
"Analyze my AMD put spread strategy with current market conditions"

Streaming Options Quotes

For real-time streaming of option quotes, use stream_option_quotes:

Important: This tool takes the underlying symbol and constructs the option symbols for you.

Correct Usage:

{
  "symbol": "AAPL",
  "strikes": "230,235,240",
  "expiration": "2025-10-17",
  "option_type": "put"
}

Parameters:

• symbol: Underlying stock symbol (e.g., "AAPL")
• strikes: Comma-separated strike prices (e.g., "230,235,240")
• expiration: Expiration date in YYYY-MM-DD format
• option_type: Either "call" or "put"
• duration: How long to stream in seconds (default: 10)

Example Questions:

"Stream option quotes for AAPL puts at strikes 230, 235, and 240 expiring 2025-10-17"
"Get real-time quotes for SPY calls at 570, 575, 580 expiring next Friday"

Note: Do NOT pass full option symbols like "AAPL 251017P00230000" - the tool constructs these for you.

Market Research

"Search for symbols related to artificial intelligence"
"Get the option chain for TSLA expiring in 30 days"
"Find options with delta around 0.30 for SPY"

Order Management

"Create a buy order for 100 shares of AAPL at market price"
"Set up a stop-loss order for my NVDA position at $200"
"Show me the status of my pending orders"

Risk Management

"Calculate the total value of my portfolio"
"Show me my unrealized P&L by position"
"What's my current buying power?"

🔧 Troubleshooting

Option Pricing Issues

If option prices aren't showing:

• Get exact symbols first: Use get_positions to see your actual option symbols
• Use correct format: Option symbols look like AAPL 251121C00150000 (not "AAPL $150 Call")
• Try direct quotes: Use get_realtime_quotes with the exact symbols from your positions

Authentication Prompts

If you keep getting "Allow" prompts:

• This is normal security behavior
• Select "Always Allow" to reduce frequency
• Each tool request requires permission for security

OAuth Setup Issues

If database mode setup fails:

• "Invalid refresh token" errors:

  • Verify you copied the refresh token correctly (no extra spaces)
  • Ensure the grant hasn't been deleted on my.tastytrade.com
  • Create a new grant if the refresh token was compromised

• "Invalid client credentials" errors:

  • Verify CLIENT_ID and CLIENT_SECRET are correct
  • Ensure no extra spaces when copying credentials
  • Check that you're using credentials from the same OAuth app

• Database connection errors:

  • Ensure write permissions in current directory
  • Try running tastytrade-mcp clean and setup again

• Token refresh failures:

  • Check that CLIENT_SECRET is correctly set in .env file
  • Verify refresh token hasn't been revoked
  • Create a new personal grant if needed

WebSocket Connection Issues

If real-time quotes aren't working:

• Check that markets are open
• Verify your internet connection
• Try reducing the duration parameter

🚀 Roadmap

Future: Full OAuth Flow (Trusted Partner)

Currently, the MCP server uses personal grant OAuth for individual use. We're planning to become a TastyTrade Trusted Partner to enable full OAuth flow:

What this means:

• ✅ One-click setup: Users can simply click "Connect with TastyTrade"
• ✅ No manual token management: Browser-based OAuth consent screen
• ✅ Multi-user support: Deploy once, serve many users
• ✅ Simpler onboarding: No need to create OAuth apps manually

Current Status: Personal grant flow (perfect for open source self-hosted use) Future Goal: Trusted partner approval for public deployments

If you're interested in helping or have feedback on this roadmap, please open a GitHub issue!

📚 Documentation

Setup Guides

• 📦 Installation - Complete installation guide
• 🖥️ Claude Desktop Setup - MCP configuration
• 💬 ChatGPT Integration - OpenAI setup
• 🔐 OAuth Database Mode - Advanced auth

Deployment

• 🚀 Deployment Overview - Cloud deployment guide

Development

• 🏗️ Architecture - System design
• 🤝 Contributing - Development guide
• 📝 Coding Standards - Code style

API Reference

• 🔧 Handlers - Available MCP tools

Supported Instrument Types

Type	Sandbox	Production	Notes
Equity (Stocks)	✅	✅	Fully tested
Equity Options	✅	✅	Single & multi-leg
Futures	❌	⚠️	Requires special account
Future Options	❌	⚠️	Requires special account
Cryptocurrency	❌	❌	Not yet supported by API

📞 Support

• Documentation: See docs/ for comprehensive guides
• Issues: Open GitHub issues for bugs or feature requests
• Security: Review our security policies before deployment

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚨 Trading Disclaimer: This software connects to real trading accounts with actual money. All trading involves financial risk. Users are responsible for their trading decisions and should understand the risks before using this tool.