Trading Simulator MCP

🚀 Trading Simulator MCP Server

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

🚀 Quick Start

This MCP server allows access to Trading Simulator operations via structured tool calls.

✨ Features

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

• Account Operations

  • Retrieve token balances
  • View portfolio information
  • Check transaction history

• Price Operations

  • Get token prices
  • View token information
  • Access price history data

• Trading Operations

  • Execute trades between two tokens
  • Obtain quotes for potential trades
  • Automatically detect tokens and handle chain parameters

• Competition Operations

  • Check competition status
  • View leaderboard rankings

📦 Installation

Run with NPX

Using Environment Variables in Cursor/Claude/Windsurf Configuration

Configure your MCP server JSON file to fit the specified consumption environment. Add this MCP in 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"
      }
    }
  }
}

Run from your terminal:

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

💻 Usage Examples

Basic Usage

The server offers the following MCP tools:

Account Tools

• get_balances - Retrieve the team's token balances
• get_portfolio - Get the team's portfolio information
• get_trades - View the team's transaction history

Price Tools

• get_price - Get the current price of a token
• get_token_info - Obtain detailed information about a token
• get_price_history - Access historical price data of a token

Trading Tools

• execute_trade - Execute a trade between two tokens
  • Automatically detect and assign chain parameters for common tokens
  • Support trading on the same chain without explicitly specifying chain parameters
  • Gracefully degrade in cross-chain scenarios
• get_quote - Get a quote for a potential trade

Competition Tools

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

🔧 Technical Details

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

Current common tokens include:

Solana (SVM)

• USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
• SOL: So1111111111111111111111111111111