io.github.hummingbot/mcp

Setup or delete an 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) Delete flow (action="delete"): 1. action="delete" only → List all accounts and their configured connectors 2. action="delete" + connector → Show which accounts have this connector configured 3. action="delete" + connector + account → Delete the credential Args: action: Action to perform. 'setup' (default) to add/update credentials, 'delete' to remove credentials. connector: Exchange connector name (e.g., 'binance', 'binance_perpetual'). Leave empty to list available connectors. credentials: Credentials object with required fields for the connector. Leave empty to see required fields first. account: Account name to add credentials to. If not provided, prompts for account selection. confirm_override: Explicit confirmation to override existing connector. Required when connector already exists.

Configure the active Hummingbot API server connection. This tool manages a single API server connection: 1. No parameters → Show the current server configuration 2. Any parameters → Update the server config and reconnect Only the provided parameters are changed; omitted ones keep their current values. Args: name: Server label (e.g., 'macmini', 'production') host: API host (e.g., 'localhost', 'host.docker.internal', '72.212.424.42') port: API port (e.g., 8000) username: API username password: API password

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. Args: account_names: List of account names to filter by (optional). If empty, returns all accounts. connector_names: List of connector names to filter by (optional). If empty, returns all connectors. include_balances: Include token balances in the overview (default: True) include_perp_positions: Include perpetual positions in the overview (default: True) include_lp_positions: Include LP (CLMM) positions in the overview (default: True) include_active_orders: Include active (open) orders in the overview (default: True) as_distribution: Show token balances as distribution percentages (default: False) refresh: If True, refresh balances from exchanges before returning. If False, return cached state (default: True)

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. Args: account_name: Account name (default: master_account) connector_name: Exchange connector name (e.g., 'binance_perpetual') trading_pair: Trading pair (e.g., ETH-USD) only required for setting leverage position_mode: Position mode ('HEDGE' or 'ONE-WAY') leverage: Leverage to set (optional, required for HEDGE mode)

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)

Get market data: prices, candles, funding rates, or order book data. Data Types: - prices: Get latest prices for multiple trading pairs - candles: Get OHLCV candle data for a trading pair - funding_rate: Get perpetual funding rate (connector must have _perpetual) - order_book: Get order book snapshot or queries Args: data_type: Type of market data to retrieve ('prices', 'candles', 'funding_rate', 'order_book') connector_name: Exchange connector name (e.g., 'binance', 'binance_perpetual') trading_pairs: List of trading pairs (required for 'prices', e.g., ['BTC-USDT', 'ETH-USD']) trading_pair: Single trading pair (required for 'candles', 'funding_rate', 'order_book') interval: Candle interval for 'candles' (default: '1h'). Options: '1m', '5m', '15m', '30m', '1h', '4h', '1d'. days: Number of days of historical data for 'candles' (default: 30). query_type: Order book query type for 'order_book' (default: 'snapshot'). Options: 'snapshot', 'volume_for_price', 'price_for_volume', 'quote_volume_for_price', 'price_for_quote_volume'. query_value: Value for order book queries (required if query_type is not 'snapshot'). is_buy: Side for order book queries (default: True for buy side).

Manage controller templates and saved configurations (design-time). Works with reusable strategy definitions and parameter sets for future deployments. Does NOT affect running bots. To modify a live bot's config, use manage_bots with action='update_config'. ⚠️ NOTE: For most trading strategies (grid, DCA, position trading), use manage_executors() instead. Only use controllers when the user EXPLICITLY asks for "controllers", "bots", or needs advanced multi-strategy bot deployments with centralized risk management. Exploration 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 config parameters template + list existing configs 4. action="describe" + config_name → Show specific config values + its controller's parameters 5. action="describe" + include_code=True → Also include the full controller source code Modification flow: 6. action="upsert" + target="controller" → Create/update a controller template 7. action="upsert" + target="config" → Create/update a saved controller config 8. action="delete" + target="controller" → Delete a controller template 9. action="delete" + target="config" → Delete a controller config 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 Trade Side (side): - 1 or "BUY" - For long/buy positions - 2 or "SELL" - For short/sell positions - 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) - Note: Numeric values are required for controller configs Args: action: "list", "describe", "upsert" (create/update), or "delete" target: "controller" (template) or "config" (instance). Required for upsert/delete. controller_type: Type of controller (e.g., 'directional_trading', 'market_making', 'generic'). controller_name: Name of the controller to describe or modify. controller_code: Code for controller (required for controller upsert). config_name: Name of the config to describe or modify. config_data: Configuration data (required for config upsert). Must include 'controller_type' and 'controller_name'. confirm_override: Required True if overwriting existing items. include_code: If True, include full controller source code in describe output. Default False.

Manage controller-based bots: deploy, monitor, get logs, control execution, and modify runtime configs. ⚠️ NOTE: For most trading strategies (grid, DCA, position trading), use manage_executors() instead. Only use bots when the user EXPLICITLY asks for "bot" deployment or needs advanced features like multi-strategy bots with centralized risk management. Actions: - deploy: Deploy a new bot with controller configurations (requires bot_name + controllers_config) - status: Get status of all active bots (no additional params needed) - logs: Get detailed logs for a specific bot (requires bot_name) - stop_bot: Stop and archive a bot forever (requires bot_name) - stop_controllers: Stop specific controllers in a bot (requires bot_name + controller_names) - start_controllers: Start/resume specific controllers (requires bot_name + controller_names) - get_config: View current configs of a running bot (requires bot_name) - update_config: Modify config of a controller INSIDE a running bot in real-time (requires bot_name + config_name + config_data) Args: action: Action to perform on bots. bot_name: Name of the bot (required for deploy, logs, stop_bot, stop/start_controllers, get_config, update_config). controllers_config: List of controller config names (required for deploy). account_name: Account name for deployment (default: master_account). max_global_drawdown_quote: Maximum global drawdown in quote currency (deploy only). max_controller_drawdown_quote: Maximum per-controller drawdown in quote currency (deploy only). image: Docker image for deployment (default: "hummingbot/hummingbot:latest"). log_type: Type of logs to retrieve for 'logs' action ('error', 'general', 'all'). limit: Maximum log entries for 'logs' action (default: 50, max: 1000). search_term: Search term to filter logs by message content (logs only). controller_names: List of controller names (required for stop/start_controllers). config_name: Name of the config to update (required for update_config). config_data: New configuration data (required for update_config). Must include 'controller_type' and 'controller_name'. confirm_override: Required True if overwriting existing config in a running bot (update_config only).

Manage trading executors: create, search, stop, and configure preferences. This is the DEFAULT tool for ALL trading operations. Use progressive disclosure to get the full guide and config schema for any executor type before creating. Executor Types (pass executor_type with no action to see full guide + schema): - order_executor: Buy/sell orders (MARKET, LIMIT, LIMIT_MAKER, LIMIT_CHASER) - position_executor: Directional positions with SL/TP management - grid_executor: Grid trading for range-bound markets - dca_executor: Dollar-cost averaging with scheduled levels - lp_executor: CLMM LP positions on Meteora/Raydium (use explore_dex_pools first) Actions: - (none) + executor_type → Show full guide, config schema, and saved defaults - create + executor_config → Create executor (merged with saved defaults) - search → List/filter executors (add executor_id for detail) - stop + executor_id → Stop executor (with keep_position option) - get_logs + executor_id → Get logs (active executors only) - get_preferences / save_preferences / reset_preferences → Manage saved defaults - positions_summary → View all positions (add connector_name + trading_pair to filter) - clear_position + connector_name + trading_pair → Clear externally-closed position Args: action: Action to perform. Leave empty to see executor types or config schema. executor_type: Type of executor. Provide alone to see its full guide and config schema. executor_config: Configuration for creating an executor. Required for 'create' action. executor_id: Executor ID for 'search' (detail), 'stop', or 'get_logs' actions. log_level: Filter logs by level - 'ERROR', 'WARNING', 'INFO', 'DEBUG' (for get_logs). account_names: Filter by account names (for search). connector_names: Filter by connector names (for search). trading_pairs: Filter by trading pairs (for search). executor_types: Filter by executor types (for search). status: Filter by status - 'RUNNING', 'TERMINATED' (for search). cursor: Pagination cursor for search results. limit: Maximum results to return (default: 50, max: 1000). keep_position: When stopping, keep the position open instead of closing it (default: False). save_as_default: Save executor_config as default for this executor_type (default: False). preferences_content: Complete markdown content for the preferences file. Required for 'save_preferences'. account_name: Account name for creating executors (default: 'master_account'). connector_name: Connector name for position filtering or clearing. trading_pair: Trading pair for position filtering or clearing.

Explore DeFi CLMM pools — discover pools, compare yields, and get pool details. Supports CLMM DEX connectors (Meteora, Raydium, Uniswap V3) for concentrated liquidity. - list_pools: Browse available CLMM pools with filtering and sorting - get_pool_info: Get detailed information about a specific pool (requires network + pool_address) To manage LP positions, use `manage_executors` with `lp_executor` type. To check on-chain positions, use `get_portfolio_overview` with `include_lp_positions=True`. Args: action: Action to perform on CLMM pools. connector: CLMM connector name (e.g., 'meteora', 'raydium', 'uniswap'). Required. network: Network ID in 'chain-network' format (e.g., 'solana-mainnet-beta'). Required for get_pool_info. pool_address: Pool contract address (required for get_pool_info). page: Page number for list_pools (default: 0). limit: Results per page for list_pools (default: 50, max: 100). search_term: Search term to filter pools by token symbols (e.g., 'SOL', 'USDC'). sort_key: Sort by field for list_pools (volume, tvl, feetvlratio, etc.). order_by: Sort order for list_pools ('asc' or 'desc'). include_unknown: Include pools with unverified tokens (default: True). detailed: Return detailed table with more columns for list_pools (default: False).

Explore DEX market data from GeckoTerminal (free, no API key needed). Progressive discovery flow: 1. action="networks" → List all supported networks (solana, eth, bsc, ...) 2. action="dexes" + network → List DEXes on a network 3. action="trending_pools" (+ network) → Trending pools globally or per network 4. action="top_pools" + network (+ dex_id) → Top pools by volume on a network/dex 5. action="new_pools" (+ network) → Recently created pools 6. action="pool_detail" + network + pool_address → Detailed info for one pool 7. action="multi_pools" + network + pool_addresses → Compare multiple pools 8. action="token_pools" + network + token_address → Top pools for a token 9. action="token_info" + network + token_address → Token details (price, mcap, fdv) 10. action="ohlcv" + network + pool_address → OHLCV candle data 11. action="trades" + network + pool_address → Recent trades Args: action: The data to retrieve. network: Network ID (e.g., 'solana', 'eth', 'bsc'). Required for most actions. dex_id: DEX ID filter for top_pools (e.g., 'raydium', 'uniswap_v3'). pool_address: Pool contract address (for pool_detail, ohlcv, trades). pool_addresses: List of pool addresses (for multi_pools). token_address: Token contract address (for token_pools, token_info). timeframe: OHLCV interval (default: '1h'). Options: 1m, 5m, 15m, 1h, 4h, 12h, 1d. before_timestamp: Fetch OHLCV candles before this unix timestamp (pagination). currency: OHLCV price currency, 'usd' or 'token' (default: 'usd'). token: Which token's price for OHLCV, 'base' or 'quote' (default: 'base'). limit: Max OHLCV candles to return (default: 1000). trade_volume_filter: Min trade volume in USD to filter trades (optional).