Hummingbot: Trading Agent

Hummingbot: Trading Agent MCP Server

Hummingbot MCP is an open-source toolset that lets you control and monitor your Hummingbot trading bots through AI-powered commands and automation.

What is an MCP Server?

MCP Info

Image Building Info

Available Tools (21)

Tools Details

Tool: configure_api_servers

Configure API servers using progressive disclosure.

This tool helps you manage multiple Hummingbot API servers with a simple flow:
1. No parameters → List all configured servers
2. action="add" + name + (optional host/port/username/password) → Add a new server
3. action="modify" + name + (host/port/username/password) → Modify existing server (partial updates supported)
4. action="set_default" + name → Set a server as default (reconnects client)
5. action="remove" + name → Remove a server

Tool: deploy_bot_with_controllers

Deploy a bot with specified controller configurations.

Tool: explore_controllers

Explore and understand controllers and their configs.

Use this tool to discover what's available and understand how things work.

Progressive flow:
1. action="list" → List all controllers and their configs
2. action="list" + controller_type → List controllers of that type with config counts
3. action="describe" + controller_name → Show controller code + list its configs + explain parameters
4. action="describe" + config_name → Show specific config details + which controller it uses

Common Enum Values for Controller Configs:

Position Mode (position_mode):
- "HEDGE" - Allows holding both long and short positions simultaneously
- "ONEWAY" - Allows only one direction position at a time
- Note: Use as string value, e.g., position_mode: "HEDGE"

Trade Side (side):
- 1 or "BUY" - For long/buy positions
- 2 or "SELL" - For short/sell positions
- 3 - Other trade types
- Note: Numeric values are required for controller configs

Order Type (order_type, open_order_type, take_profit_order_type, etc.):
- 1 or "MARKET" - Market order
- 2 or "LIMIT" - Limit order
- 3 or "LIMIT_MAKER" - Limit maker order (post-only)
- 4 - Other order types
- Note: Numeric values are required for controller configs

Tool: explore_gateway_clmm_pools

Explore Gateway CLMM pools: list pools and get pool information.

Supports CLMM DEX connectors (Meteora, Raydium, Uniswap V3) for concentrated liquidity pools.

Actions:
- list_pools: Browse available CLMM pools with filtering and sorting
- get_pool_info: Get detailed information about a specific pool (requires network and pool_address)

Tool: get_active_bots_status

Get the status of all active bots. Including the unrealized PnL, realized PnL, volume traded, latest logs, etc. Note: Both error logs and general logs are limited to the last 5 entries. Use get_bot_logs for more detailed log searching.

Tool: get_bot_logs

Get detailed logs for a specific bot with filtering options.

Tool: get_candles

Get the real-time candles for a trading pair on a specific exchange connector.

Tool: get_funding_rate

Get the latest funding rate for a trading pair on a specific exchange connector. Only works for perpetual connectors so the connector name must have _perpetual in it.

Tool: get_order_book

Get order book data for a trading pair on a specific exchange connector, if the query type is different than snapshot, you need to provide query_value and is_buy

Tool: get_portfolio_overview

Get a unified portfolio overview with balances, perpetual positions, LP positions, and active orders.

This tool provides a comprehensive view of your entire portfolio by fetching data from multiple sources
in parallel. By default, it returns all four types of data, but you can filter to only include
specific sections.

Data Sources (fetched in parallel using asyncio.gather):
1. Token Balances - Holdings across all connected CEX/DEX exchanges
2. Perpetual Positions - Open perpetual futures positions from CEX
3. LP Positions (CLMM) - Real-time concentrated liquidity positions from blockchain DEXs
   - Queries database to find all pools user has interacted with
   - Calls get_positions() for each pool to fetch real-time blockchain data
   - Includes real-time fees and token amounts
4. Active Orders - Currently open orders across all exchanges

NOTE: This only shows ACTIVE/OPEN positions. For historical data, use search_history() instead.

Tool: get_prices

Get the latest prices for the specified trading pairs on a specific exchange connector.

Tool: manage_bot_execution

Manage bot and controller execution states.

Actions:
- "stop_bot": Stop and archive the entire bot forever (controller_names not needed)
- "stop_controllers": Stop specific controllers by setting manual_kill_switch to True (requires controller_names)
- "start_controllers": Start/resume specific controllers by setting manual_kill_switch to False (requires controller_names)

Tool: manage_gateway_clmm_positions

Manage Gateway CLMM positions: open, close, collect fees, and get positions.

Supports CLMM DEX connectors (Meteora, Raydium, Uniswap V3) for concentrated liquidity positions.

Actions:
- open_position: Create a new CLMM position with initial liquidity
- close_position: Close a position completely (removes all liquidity)
- collect_fees: Collect accumulated fees from a position
- get_positions: Get all positions owned by a wallet for a specific pool (fetches real-time data from blockchain)

Open Position Parameters (required for open_position):
    connector: CLMM connector name (e.g., 'meteora', 'raydium')
    network: Network ID in 'chain-network' format (e.g., 'solana-mainnet-beta')
    pool_address: Pool contract address
    lower_price: Lower price bound (e.g., '150')
    upper_price: Upper price bound (e.g., '250')
    base_token_amount: Amount of base token to provide (optional)
    quote_token_amount: Amount of quote token to provide (optional)
    slippage_pct: Maximum slippage percentage (default: 1.0)
    wallet_address: Wallet address (optional, uses default if not provided)
    extra_params: Additional connector-specific parameters (e.g., {"strategyType": 0} for Meteora)

Close/Collect Parameters (required for close_position and collect_fees):
    connector: CLMM connector name
    network: Network ID in 'chain-network' format
    position_address: Position NFT address
    wallet_address: Wallet address (optional)

Get Positions Parameters (required for get_positions):
    connector: CLMM connector name
    network: Network ID in 'chain-network' format
    pool_address: Pool contract address
    wallet_address: Wallet address (optional)

Tool: manage_gateway_config

Manage Gateway configuration for chains, networks, tokens, connectors, pools, and wallets.

Resource Types:
- chains: Get all blockchain chains
- networks: List/get/update network configurations (format: 'chain-network')
- tokens: List/add/delete tokens per network
- connectors: List/get/update DEX connector configurations
- pools: List/add liquidity pools per connector/network
- wallets: Add/delete wallets for blockchain chains

Tool: manage_gateway_container

Manage Gateway container lifecycle operations.

Supports:
- get_status: Check Gateway container status
- start: Start Gateway with configuration
- stop: Stop Gateway container
- restart: Restart Gateway (optionally with new config)
- get_logs: Get container logs

Tool: manage_gateway_swaps

Manage Gateway swap operations: quote, execute, search swaps.

Supports DEX router swaps via Jupiter (Solana) and 0x (Ethereum).

Actions:
- quote: Get price quote for a swap before executing
- execute: Execute a swap transaction on DEX
- search: Search swap history with filters
- get_status: Get status of a specific swap by transaction hash

Quote/Execute Parameters (required for quote/execute):
    connector: DEX router connector (e.g., 'jupiter', '0x')
    network: Network ID in 'chain-network' format (e.g., 'solana-mainnet-beta', 'ethereum-mainnet')
    trading_pair: Trading pair in BASE-QUOTE format (e.g., 'SOL-USDC', 'ETH-USDT')
    side: Trade side - 'BUY' (buy base with quote) or 'SELL' (sell base for quote)
    amount: Amount to swap (for BUY: base to receive, for SELL: base to sell)
    slippage_pct: Maximum slippage percentage (default: 1.0)
    wallet_address: Wallet address for execute (optional, uses default if not provided)

Get Status Parameters:
    transaction_hash: Transaction hash to check status

Search Parameters (all optional):
    search_connector: Filter by connector
    search_network: Filter by network
    search_wallet_address: Filter by wallet address
    search_trading_pair: Filter by trading pair
    status: Filter by status (SUBMITTED, CONFIRMED, FAILED)
    start_time: Start timestamp (unix seconds)
    end_time: End timestamp (unix seconds)
    limit: Max results (default: 50, max: 1000)
    offset: Pagination offset (default: 0)

Tool: modify_controllers

Create, update, or delete controllers and their configurations. If bot name is provided, it can only modify the config in the bot deployed with that name.

IMPORTANT: When creating a config without specifying config_data details, you MUST first use the explore_controllers tool
with action="describe" and the controller_name to understand what parameters are required. The config_data must include
ALL relevant parameters for the controller to function properly.

Controllers = are essentially strategies that can be run in Hummingbot.
Configs = are the parameters that the controller uses to run.

Tool: place_order

Place a buy or sell order on a OrderBook Exchange (supports USD values by adding at the start of the amount $).

Tool: search_history

Search historical data from the backend database.

This tool is for historical analysis, reporting, and tax purposes.
For real-time current state, use get_portfolio_overview() instead.

Data Types:
- orders: Historical order data (filled, cancelled, failed)
- perp_positions: Perpetual positions (both open and closed)
- clmm_positions: CLMM LP positions (both open and closed)

Common Filters (apply to all data types):
    account_names: Filter by account names (optional)
    connector_names: Filter by connector names (optional)
    trading_pairs: Filter by trading pairs (optional)
    status: Filter by status (optional, e.g., 'OPEN', 'CLOSED', 'FILLED', 'CANCELED')
    start_time: Start timestamp in seconds (optional)
    end_time: End timestamp in seconds (optional)
    limit: Maximum number of results (default: 50, max: 1000)
    offset: Pagination offset (default: 0)

CLMM-Specific Filters:
    network: Network filter for CLMM positions (optional)
    wallet_address: Wallet address filter for CLMM positions (optional)
    position_addresses: Specific position addresses for CLMM (optional)

Examples:
- Search filled orders: search_history("orders", status="FILLED", limit=100)
- Search closed perp positions: search_history("perp_positions", status="CLOSED")
- Search all CLMM positions: search_history("clmm_positions", limit=100)

Tool: set_account_position_mode_and_leverage

Set position mode and leverage for an account on a specific exchange. If position mode is not specified, will only set the leverage. If leverage is not specified, will only set the position mode.

Tool: setup_connector

Setup a new exchange connector for an account with credentials using progressive disclosure.

This tool guides you through the entire process of connecting an exchange with a four-step flow:
1. No parameters → List available exchanges
2. Connector only → Show required credential fields
3. Connector + credentials, no account → Select account from available accounts
4. All parameters → Connect the exchange (with override confirmation if needed)

Use this MCP Server

{
  "mcpServers": {
    "hummingbot-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HUMMINGBOT_API_URL",
        "-e",
        "HUMMINGBOT_API_USERNAME",
        "-e",
        "HUMMINGBOT_API_PASSWORD",
        "hummingbot/hummingbot-mcp"
      ],
      "env": {
        "HUMMINGBOT_API_URL": "http://localhost:8000",
        "HUMMINGBOT_API_USERNAME": "admin",
        "HUMMINGBOT_API_PASSWORD": "password"
      }
    }
  }
}

Why is it safer to run MCP Servers with Docker?