Trading Simulator MCP Server

An MCP (Model Context Protocol) server for interacting with the Trading Simulator API. This server enables AI models like Claude to check balances, check prices, and execute trades via an MCP-compatible interface.

Features

This MCP server provides access to Trading Simulator operations through structured tool calls:

Account Operations
- Get token balances
- Get portfolio information
- View trade history
Price Operations
- Get token prices
- Get token information
- View price history
Trading Operations
- Execute trades between tokens
- Get quotes for potential trades
- Smart token detection that automatically handles chain parameters
Competition Operations
- Check competition status
- View leaderboard rankings

Usage Using NPX

Using Environment Variables in Cursor/Claude/Windsurf Configuration

Configure your MCP servers JSON file for your designated consuming environment by adding this MCP using the following format:

{
  "mcpServers": {
    "trading-simulator-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:recallnet/trading-simulator-mcp"
      ],
      "env": {
        "TRADING_SIM_API_KEY": "your-api-key",
        "TRADING_SIM_API_URL": "api-url"
      }
    }
  }
}

Running it from your terminal:

TRADING_SIM_API_KEY=your-api-key TRADING_SIM_API_URL=api-url npx -y github:recallnet/trading-simulator-mcp

MCP Tools

The server provides the following MCP tools:

Account Tools

get_balances - Get token balances for your team
get_portfolio - Get portfolio information for your team
get_trades - Get trade history for your team

Price Tools

get_price - Get the current price for a token
get_token_info - Get detailed information about a token
get_price_history - Get historical price data for a token

Trading Tools

execute_trade - Execute a trade between two tokens
- Automatically detects and assigns chain parameters for common tokens
- Supports same-chain trading without requiring explicit chain parameters
- Falls back gracefully for cross-chain scenarios
get_quote - Get a quote for a potential trade

Competition Tools

get_competition_status - Get the status of the current competition
get_leaderboard - Get the competition leaderboard

Common Tokens

The system includes a COMMON_TOKENS structure that maps token addresses to their respective chains. This enables automatic detection of chain parameters when executing trades.

Current common tokens include:

Solana (SVM)

USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
SOL: So11111111111111111111111111111111111111112

Ethereum (EVM)

USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
WETH: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

Base (EVM)

USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
ETH: 0x4200000000000000000000000000000000000006

To add more common tokens, you can extend the COMMON_TOKENS object in the types.ts file.

Security Considerations

Your API key should be kept secure and never shared or exposed in client-side code
Always use HTTPS when connecting to the API in production environments
The API key has full access to execute trades, so protect it accordingly