ReadyTrader-Stocks

ReadyTrader-Stocks provides a dedicated MCP server that acts as the safety-and-keys guard for your AI trading agent. It sits between your AI’s trading ideas and the broker, enforcing risk rules, handling API keys securely, and enabling controlled execution of trades. This guide shows you how to use the MCP server with an MCP client, how to install it locally or in a container, and how to configure integration with your agent.

How to use

Connect an MCP client to the ReadyTrader-Stocks MCP server to enable AI-assisted trading with risk controls. You can run the server locally or inside a container and provide your paper-mode or live-mode settings via environment variables. Use the client to request data, run backtests, and place orders, while the MCP server enforces safety limits and routing to your broker.

Typical usage flow:

• Your agent researches assets and generates trade ideas
• The agent requests market data and sentiment through the MCP interface
• The agent proposes an order; the MCP server validates it against your risk rules
• If approval is required, you review and confirm in the client UI before execution

Supported integration approaches include a stdio MCP client configuration (local process) or a remote HTTP MCP server setup. The server exposes an interface for agents to fetch data, run backtests, and place orders while keeping your API keys and risk controls centralized in the MCP layer.

How to install

Prerequisites: You need Docker (Docker Compose is optional) and a Python environment if you want to run the server without Docker.

Install and run in a container

cd ReadyTrader-Stocks
docker build -t readytrader-stocks .
# Run interactively to test
docker run --rm -i readytrader-stocks```

Local development (no Docker)

pip install -r requirements-dev.txt
python app/main.py

Configuration and security

Customize how the MCP server runs by creating a .env file or using env vars. Start from env.example and copy to .env to customize values.

Live trading safety and approval settings include options to enable or disable paper mode, require human approval for trades, and set global risk controls. Example settings covered in the environment configuration include:

• PAPER_MODE: true or false
• LIVE_TRADING_ENABLED: true to enable live trading
• EXECUTION_APPROVAL_MODE: auto or approve_each
• RISK_PROFILE: conservative, balanced, or aggressive
• MARKETDATA_EXCHANGES and tickers allowlists for data routing

Integration guides and MCP server configurations

Option A: Agent Zero (recommended) integrates the MCP server by running a container with PAPER_MODE preset. Copy/paste the following configuration into your agent settings to point to the ReadyTrader-Stocks MCP server.

mcp_servers:
  readytrader_stocks:
    command: "docker"
    args: 
      - "run"
      - "-i" 
      - "--rm"
      - "-e"
      - "PAPER_MODE=true"
      - "readytrader-stocks"

Option B: Generic MCP Client (Claude Desktop, etc.) uses a JSON config to connect to the same server. Add this to your mcp-server-config.json.

{
  "mcpServers": {
    "readytrader_stocks": {
      "command": "docker",
      "args": [
        "run", 
        "-i", 
        "--rm", 
        "-e", 
        "PAPER_MODE=true", 
        "readytrader-stocks"
      ]
    }
  }
}

Key MCP commands and tools

The server provides a set of tools for data retrieval, trading actions, and strategy testing. Common actions include fetching market data, placing orders, running backtests, and simulating stress scenarios.

Synthetic stress testing

The MCP includes a deterministic synthetic market simulator for evaluating strategies under varied regimes and black-swan events. You can run a test with parameters that define seeds, scenario count, and market behavior to obtain metrics and recommendations.

{
  "master_seed": 123,
  "scenarios": 200,
  "length": 500,
  "timeframe": "1h",
  "initial_capital": 10000,
  "start_price": 100,
  "base_vol": 0.01,
  "black_swan_prob": 0.02,
  "parabolic_prob": 0.02
}

Available tools

fetch_ohlcv

Retrieve historical OHLCV candles for research and backtesting.

get_sentiment

Obtain real-time sentiment signals to inform trading decisions.

place_market_order

Submit a market order to buy or sell a specified quantity.

deposit_paper_funds

Add virtual funds to the paper wallet for zero-risk testing.

reset_paper_wallet

Reset all simulated data and balances to start fresh.

run_backtest_simulation

Execute a backtest of a trading strategy on historical data.

get_portfolio_balance

Check the current balance of the paper or live account.

get_stock_price

Fetch live price data for a given ticker from market data providers.