skillbase/hummingbot-mcp

## The 11 MCP Tools

### 1. `configure_server`

Configure the Hummingbot API server connection.

```

configure_server(

  name: str?,         # server name

  host: str?,         # API host

  port: int?,         # API port

  username: str?,     # HTTP Basic Auth user

  password: str?      # HTTP Basic Auth password

)

```

- No params → show current config

- Any params → update and reconnect (only provided params change)

### 2. `setup_connector`

Setup or delete exchange connectors with credentials.

```

setup_connector(

  action: "setup" | "delete"?,

  connector: str?,            # exchange name (e.g. "binance", "okx")

  credentials: dict?,         # API key/secret/passphrase

  account: str?,              # account name

  confirm_override: bool?     # confirm replacing existing credentials

)

```

**Setup flow (progressive disclosure):**

1. No params → list all available exchanges

2. `connector="binance"` → show required credential fields for that exchange

3. `connector + credentials` → list available accounts to attach to

4. `connector + credentials + account` → connect

**Delete flow:**

1. `action="delete"` → list accounts and their connectors

2. `+ connector` → show which accounts have it

3. `+ connector + account` → delete

### 3. `get_portfolio_overview`

Unified view of balances, positions, and orders.

```

get_portfolio_overview(

  account_names: list[str]?,        # filter by accounts

  connector_names: list[str]?,      # filter by exchanges

  include_balances: bool = True,

  include_perp_positions: bool = True,

  include_lp_positions: bool = True,

  include_active_orders: bool = True,

  as_distribution: bool = False,    # show as % distribution

  refresh: bool = True              # fetch fresh data vs cache

)

```

Fetches 4 data sources in parallel: token balances, perpetual positions, CLMM LP positions (with real-time blockchain data), active orders. Only shows ACTIVE/OPEN items. For historical data use `search_history`.

### 4. `set_account_position_mode_and_leverage`

Configure perpetual trading settings.

```

set_account_position_mode_and_leverage(

  account_name: str,          # required

  connector_name: str,        # required

  trading_pair: str?,         # required for leverage

  position_mode: str?,        # "HEDGE" or "ONE-WAY"

  leverage: int?              # leverage multiplier

)

```

### 5. `get_market_data`

Real-time and historical market data from connected exchanges.

```

get_market_data(

  data_type: "prices" | "candles" | "funding_rate" | "order_book",

  connector_name: str,                    # exchange name

  trading_pairs: list[str]?,              # for prices (multiple)

  trading_pair: str?,                     # for candles/book (single)

  interval: str = "1h",                  # 1m, 5m, 15m, 30m, 1h, 4h, 1d

  days: int = 30,                        # candle history depth

  query_type: str?,                      # order book query mode

  query_value: float?,                   # value for order book query

  is_buy: bool = True                    # direction for order book query

)

```

**Order book query types:**

- `snapshot` — full order book

- `price_for_volume` — what price to fill X base tokens

- `volume_for_price` — how much volume at price X

- `quote_volume_for_price` — quote volume at price X

- `price_for_quote_volume` — price to fill X quote tokens

Use `price_for_volume` before large orders to estimate slippage.

### 6. `manage_controllers`

Design-time management of strategy templates and configs. Does NOT affect running bots.

```

manage_controllers(

  action: "list" | "describe" | "upsert" | "delete",

  target: "controller" | "config"?,

  controller_type: "directional_trading" | "market_making" | "generic"?,

  controller_name: str?,

  controller_code: str?,          # Python code for custom controllers

  config_name: str?,

  config_data: dict?,             # YAML config as dict

  confirm_override: bool = False,

  include_code: bool = False      # include source code in describe

)

```

**Exploration flow:**

1. `action="list"` → list all controller types

2. `+ controller_type="market_making"` → list controllers of that type

3. `+ controller_name="pmm_simple"` → describe controller schema + params

4. `+ config_name="my_config"` → describe saved config

5. `+ include_code=True` → include Python source

**Available controllers:**

- **market_making**: `dman_maker_v2`, `pmm_dynamic`, `pmm_simple`

- **directional_trading**: `ai_livestream`, `bollinger_v1`, `bollinger_v2`, `dman_v3`, etc.

- **generic**: `arbitrage_controller`, `grid_strike`, `hedge_asset`, etc.

**Common enum values in configs:**

- position_mode: `HEDGE`, `ONEWAY`

- side: `1` = BUY, `2` = SELL

- order_type: `1` = MARKET, `2` = LIMIT, `3` = LIMIT_MAKER

### 7. `manage_bots`

Runtime bot management: deploy, monitor, control.

```

manage_bots(

  action: "deploy" | "status" | "logs" | "stop_bot" | "stop_controllers" | "start_controllers" | "get_config" | "update_config",

  bot_name: str?,

  controllers_config: list[str]?,            # config names to deploy

  account_name: str? = "master_account",

  max_global_drawdown_quote: float?,         # portfolio-level stop loss ($)

  max_controller_drawdown_quote: float?,     # per-controller stop loss ($)

  image: str = "hummingbot/hummingbot:latest",

  log_type: "error" | "general" | "all" = "all",

  limit: int = 50,

  search_term: str?,                         # filter logs

  controller_names: list[str]?,              # for stop/start specific controllers

  config_name: str?,                         # for update_config

  config_data: dict?,                        # new config values

  confirm_override: bool = False

)

```

**Key actions:**

- `deploy`: bot_name + controllers_config + account_name. Set drawdown limits here.

- `status`: no params → all bots. bot_name → specific bot.

- `logs`: bot_name required. Use search_term to filter.

- `stop_bot`: graceful stop of entire bot

- `stop_controllers` / `start_controllers`: selective control of controllers within a bot

- `get_config` / `update_config`: runtime config modification

**Built-in risk controls:**

- `max_global_drawdown_quote` — stops ALL controllers when total loss exceeds this (in quote currency $)

- `max_controller_drawdown_quote` — stops individual controller when its loss exceeds this

### 8. `manage_executors`

**The primary trading tool.** Direct order execution and position management.

```

manage_executors(

  action: "create" | "search" | "stop" | "get_logs" | "get_preferences" | "save_preferences" | "reset_preferences" | "positions_summary" | "clear_position"?,

  executor_type: str?,              # see types below

  executor_config: dict?,           # execution params

  executor_id: str?,                # for stop/logs

  account_names: list[str]?,

  connector_names: list[str]?,

  trading_pairs: list[str]?,

  executor_types: list[str]?,       # filter by type

  status: str?,                     # filter by status

  cursor: str?,                     # pagination

  limit: int = 50,

  keep_position: bool = False,      # on stop: keep or close position

  save_as_default: bool = False,

  preferences_content: str?,

  account_name: str?,

  connector_name: str?,

  trading_pair: str?

)

```

**Executor types:**

- `order_executor` — single order: MARKET, LIMIT, LIMIT_MAKER, LIMIT_CHASER

- `position_executor` — directional trade with stop-loss and take-profit

- `grid_executor` — grid of orders in a price range

- `dca_executor` — dollar-cost averaging

- `lp_executor` — CLMM liquidity provision on Meteora/Raydium

**Progressive disclosure:** call with just `executor_type` to get full guide + schema + current defaults.

**Preferences:** save default execution settings per executor type to avoid re-specifying common params.

### 9. `search_history`

Query historical data from the database.

```

search_history(

  data_type: "orders" | "perp_positions" | "clmm_positions",

  account_names: list[str]?,

  connector_names: list[str]?,

  trading_pairs: list[str]?,

  status: str?,

  start_time: int?,          # unix timestamp

  end_time: int?,            # unix timestamp

  limit: int = 50,

  offset: int = 0,

  network: str?,             # CLMM filter

  wallet_address: str?,      # CLMM filter

  position_addresses: list[str]?  # CLMM filter

)

```

### 10. `explore_dex_pools`

Discover CLMM pools on supported DEXs.

```

explore_dex_pools(

  action: "list_pools" | "get_pool_info",

  connector: str?,           # "meteora", "raydium", "uniswap_v3"

  network: str?,

  pool_address: str?,        # for get_pool_info

  page: int = 0,

  limit: int = 50,

  search_term: str?,         # filter by token name

  sort_key: str? = "volume", # sort field

  order_by: str? = "desc",

  include_unknown: bool = True,

  detailed: bool = False

)

```

### 11. `explore_geckoterminal`

Free DEX market data from GeckoTerminal (no API key needed).

```

explore_geckoterminal(

  action: "networks" | "dexes" | "trending_pools" | "top_pools" | "new_pools" | "pool_detail" | "multi_pools" | "token_pools" | "token_info" | "ohlcv" | "trades",

  network: str?,

  dex_id: str?,

  pool_address: str?,

  pool_addresses: list[str]?,

  token_address: str?,

  timeframe: str = "1h",          # 1m, 5m, 15m, 1h, 4h, 12h, 1d

  before_timestamp: int?,

  currency: str = "usd",

  token: str = "base",

  limit: int = 1000,

  trade_volume_filter: float?

)

```

**Discovery flow:** networks → dexes → trending_pools/top_pools/new_pools → pool_detail → ohlcv → trades

Useful for researching DEX markets without connecting an exchange.

## Operational Workflows

### First-time setup

1. `configure_server()` → verify connection

2. `setup_connector()` → list exchanges

3. `setup_connector(connector="binance")` → see required fields

4. `setup_connector(connector="binance", credentials={...}, account="main")` → connect

5. `get_portfolio_overview()` → verify balances appear

### Deploy a market making bot

1. `manage_controllers(action="list", controller_type="market_making")` → see available controllers

2. `manage_controllers(action="describe", controller_name="pmm_simple")` → get config schema

3. `manage_controllers(action="upsert", target="config", config_name="my_pmm", config_data={...})` → save config

4. `manage_bots(action="deploy", bot_name="mm-bot-1", controllers_config=["my_pmm"], max_global_drawdown_quote=500)` → deploy

5. `manage_bots(action="status", bot_name="mm-bot-1")` → verify running

6. `get_portfolio_overview(include_active_orders=True)` → verify orders placed

### Quick manual trade

1. `manage_executors(executor_type="order_executor")` → get schema and defaults

2. `manage_executors(action="create", executor_type="order_executor", executor_config={...})` → place order

3. `manage_executors(action="search", status="active")` → monitor

### Monitor operations

1. `manage_bots(action="status")` → all bot statuses

2. `get_portfolio_overview()` → balances + positions + orders

3. `manage_executors(action="search", status="active")` → active executors

4. `manage_bots(action="logs", bot_name="mm-bot-1", log_type="error")` → check for errors

### Research DEX opportunities

1. `explore_geckoterminal(action="trending_pools", network="solana")` → find hot pools

2. `explore_geckoterminal(action="pool_detail", network="solana", pool_address="...")` → pool details

3. `explore_dex_pools(action="list_pools", connector="raydium")` → pools available for LP

4. `explore_dex_pools(action="get_pool_info", network="solana", pool_address="...")` → detailed info

### Emergency stop

1. `manage_bots(action="stop_bot", bot_name="mm-bot-1")` → stop specific bot

2. `get_portfolio_overview(include_active_orders=True)` → verify no orphan orders

3. `get_portfolio_overview()` → snapshot state for incident analysis