Paper Trading MCP Server with 22 Broker Emulations

Overview

The Paper Trading MCP Server is a local development server that emulates trading brokers and market behavior for risk-free, institutional-style paper trading. It implements the Model Context Protocol (MCP) to provide a consistent API surface for sending orders, subscribing to market data, and inspecting simulated accounts and fills. By running an MCP server locally or in a test environment, teams can validate execution logic, integration code, and trading strategies without touching live markets or real accounts.

This server includes 22 broker emulations and a suite of professional tools for realistic testing: order book and trade simulation, configurable latency and slippage, historical replay, and account/position management. It’s useful for engineers building broker-agnostic systems, QA teams validating order routing, quant researchers testing live-like behavior, and educators teaching execution concepts.

Features

• 22 broker emulations for realistic, broker-specific behavior (order types, fills, fees)
• MCP-compatible API for orders, market data, accounts, and positions
• REST and WebSocket endpoints for low-latency streaming and control
• Market simulation with configurable latency, slippage, and partial fills
• Historical replay and time-acceleration modes for testing
• Account and portfolio views including margin, balances, and P&L
• Logging, metrics, and hooks for integration testing and CI
• Docker-friendly deployment for consistent local and CI environments
• Extensible adapters to add custom broker behaviors or instruments

Installation / Configuration

Clone the repository and choose a deployment method: Docker (recommended) or local Node runtime.

Clone repo:

git clone https://github.com/paperinvest/mcp-server.git
cd mcp-server

Docker (quick start):

# Copy example env and start the server with docker-compose
cp .env.example .env
docker-compose up --build -d

Local Node (development):

# Install and run (if the project uses Node/TypeScript)
cp .env.example .env
# adjust environment values in .env
npm install
npm run dev

Example .env (minimum):

# Server bindings
MCP_HOST=0.0.0.0
MCP_PORT=8080

# Broker selection (comma-separated names or "all")
BROKER_EMULATIONS=all

# Simulation tuning
SIMULATION_LATENCY_MS=30
SIMULATION_SLIPPAGE_PCT=0.001

# Persistence / logs
DATA_DIR=./data
LOG_LEVEL=info

Configuration notes:

• Use BROKER_EMULATIONS to enable specific emulations or “all”.
• Tune latency and slippage to approximate production conditions.
• Persisted data (orders, accounts) is stored under DATA_DIR; mount a volume in Docker for longevity.
• The repo provides .env.example and docker-compose.yml with sensible defaults.

Available Resources

The server exposes REST and WebSocket endpoints for integration. Typical endpoints include:

• REST

  • POST /mcp/orders — submit a new order
  • GET /mcp/orders/{id} — retrieve order status
  • GET /mcp/accounts/{id} — account info and balances
  • GET /mcp/positions — list current positions
  • POST /mcp/simulation/replay — start historical replay

• WebSocket (MCP stream)

  • /mcp/ws — subscribe to market data, order updates, fills, and simulation events

Example REST call (place a limit order):

curl -X POST http://localhost:8080/mcp/orders \
  -H "Content-Type: application/json" \
  -d '{
    "accountId":"paper-001",
    "broker":"alpaca", 
    "symbol":"AAPL",
    "side":"buy",
    "type":"limit",
    "price":150.00,
    "quantity":10
  }'

Example WebSocket subscription (pseudo):

const ws = new WebSocket('ws://localhost:8080/mcp/ws');
ws.onopen = () => ws.send(JSON.stringify({ type: 'subscribe', channels: ['orders', 'trades', 'book:AAPL'] }));
ws.onmessage = msg => console.log('mcp event', JSON.parse(msg.data));

Available client libraries and examples are included in the repo to demonstrate MCP message formats and reconnection/heartbeat handling.

Available Tools

• Admin UI / CLI for managing simulated accounts, resetting state, and toggling brokers
• Replay tool to feed historical market data into simulations with adjustable speed
• Metrics endpoints (Prometheus compatible) and structured logs for CI integration
• Hooks to persist simulated state into databases or export for audit

Sample table: example broker emulations (subset)

(Full list of 22 emulations is available in the repository’s docs and configuration files.)

Use Cases

• Algorithm testing: Run a strategy against live-like simulated fills and market data to validate P&L, risk limits, and edge cases before connecting to a broker.
• Integration testing: CI pipelines can spin up the MCP server to validate order lifecycle and error handling for multiple brokers without external dependencies.
• End-to-end QA: Simulate broker-specific behavior (partial fills, rejections, margin calls) to validate client UI/UX and back-office flows.
• Educational sandboxes: Teach order types, market microstructure, and execution algorithms in a controlled, repeatable environment.
• Research and replay: Reproduce historical market scenarios to evaluate strategy robustness under varying latency and slippage settings.

If you need to extend the server, the repository includes adapter templates and a plugin model for adding new broker emulations, custom instruments, and bespoke simulation rules. Check the docs directory in the repo for API schemas, MCP message formats, and adapter guides.