← Back to directory

Hummingbot MCP Server

Official

Archived

Connect Hummingbot via MCP for automated multi-exchange crypto trading

How to install ↓ Compare GitHub source repository ↗

Category: Dev Tools #243 of 438
Stars: ★ 59 Popular
Transport: stdio (local process)
Runtime: Python 3.11+ · Docker
Credentials: API key / credential required
License: Apache-2.0
Last commit: 7 months ago ⚠
Tools: 1

51FMRS · D

An officially maintained MCP server from Hummingbot that connects Claude and Gemini CLI over stdio to accounts, orders, positions, market data, and bot management tools. Well documented with uv and Docker paths and clear error messages, but only suitable for users who already run Hummingbot infrastructure.

Strongest · Documentation 14/20 Weakest · Security and permissions 6/20

Reliability

9/20

Security and permissions

6/20

Maintenance

10/20

Documentation

14/20

Setup experience

12/20

Why each score

Reliability 9/20: server.json declares a single OCI package with stdio transport and three well-formed environment variables, and the package version (1.0.4) matches the top-level version, showing some consistency. The README also describes concrete error-handling behavior (no retry on 401, retries on connection failure), suggesting engineering care. However, no verifiable tool list is provided — the README only groups tools into broad categories ('account management', 'order placement', 'position management', etc.) without naming individual tools, parameters, or return shapes — so declared tools cannot be checked against real behavior. No CI workflow or committed test files are present as static evidence (the README only mentions `uv run pytest` can be run, without showing test content). Per the static calibration rule, reliability is capped at 12 absent verifiable execution evidence, so a moderate-low score is given.
Security and permissions 6/20: Credentials are passed via environment variables and username/password are correctly flagged isSecret in the manifest, with no plaintext tokens shown in the documentation — a positive. However, this server controls automated trading with real funds (order placement, position management, bot deployment) with a broad permission scope, and none of the provided material describes any confirmation step before dangerous financial operations, a dry-run/simulation mode, scoping/allow-listing, or rate limiting. For a system capable of executing real-money trades, this absence of confirmation and least-privilege evidence is a serious gap; it does not clearly cross the red-line threshold (no documentation explicitly states trades execute by default without confirmation), but the risk sits close to that line, warranting a low score.
Maintenance 10/20: The license is Apache-2.0, the repository is not archived, and the version number 1.0.4 implies multiple prior releases, indicating some ongoing maintenance. However, the supplied material contains no visible commit history, release cadence, issue response times, dependency-update record, or security-response channel, making it hard to judge the maturity of project governance, resulting in a middling score.
Documentation 14/20: The README is thorough, covering both uv and Docker installation paths, a docker-compose example for cloud deployment, an environment-variable reference table, usage examples for the configure_server tool, and a dedicated troubleshooting section — well-layered and actionable. It falls short of full marks because it lacks per-tool parameter-level documentation (tools are only grouped by category), omits any cost/rate-limit disclosure, and does not describe data-flow boundaries or known limitations.
Setup experience 12/20: Setup instructions are clear and cover three paths — local uv execution, single-container Docker, and full docker-compose deployment — with concrete client configuration JSON for Claude Code/Gemini CLI, indicating decent mainstream-client compatibility. Still, the overall setup is not simple: it depends on a separately running Hummingbot API service, Docker networking differs by OS (--network host on Linux vs. host.docker.internal on Mac/Windows), and the cloud deployment path requires standing up additional services (Postgres, EMQX), making it a moderately complex manual process. Per the static calibration rule, setup is capped at 15 without CI/test-based execution evidence, so a moderate score is given.

Static review · not runListed 2026-09-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account data

Best for

Users already running Hummingbot API who want AI-client control of trading
Crypto traders comfortable with Docker/uv configuration

Not for

Users without Hummingbot or a running API server
Beginners without trading background who cannot absorb automated-trading risk

Required permissions

Requires Hummingbot API username and password (HUMMINGBOT_USERNAME, HUMMINGBOT_PASSWORD)
Requires a reachable Hummingbot API URL (HUMMINGBOT_API_URL)
Docker deployment mounts ~/.hummingbot_mcp to persist configuration

Risks and side effects

The server can place real trade orders; misconfiguration can lead to financial loss
API credentials are stored in environment variables and .env files and must be protected
Connecting to a wrong URL or exposing the API publicly introduces security risk

Setup

Before you start

Runtime：Python 3.11+ · Docker

HUMMINGBOT_API_URL required Base URL of the Hummingbot API (e.g. http://localhost:8000); used only on first run to build the default config; use host.docker.internal in Docker on Mac/Windows.

HUMMINGBOT_USERNAME requiredsecret Hummingbot API username; used only on first run for the initial config.

HUMMINGBOT_PASSWORD requiredsecret Hummingbot API password (secret); used only on first run for the initial config.

Other optional settings (4)

HUMMINGBOT_TIMEOUT optional Connection timeout in seconds; default 30.0.

HUMMINGBOT_MAX_RETRIES optional Maximum number of retry attempts; default 3.

HUMMINGBOT_RETRY_DELAY optional Delay between retries in seconds; default 2.0.

HUMMINGBOT_LOG_LEVEL optional Logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL); default INFO.

1) uv: install uv, clone https://github.com/hummingbot/mcp, run uv sync, copy .env.example to .env with HUMMINGBOT_API_URL, HUMMINGBOT_USERNAME, HUMMINGBOT_PASSWORD, then configure the client to run main.py via uv. 2) Docker: create .env, pull hummingbot/hummingbot-mcp:latest, use --network host on Linux or set the API URL to http://host.docker.internal:8000 on Mac/Windows, then configure a docker run command in the client. Alternatively deploy with Docker Compose alongside hummingbot-api, emqx, and postgres. Requires Python 3.11+ and a running Hummingbot API.

.mcp.json

{"mcpServers":{"hummingbot-mcp":{"type":"stdio","command":"uv","args":["--directory","/path/to/mcp","run","main.py"]}}}

Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

{
  "servers": {
    "hummingbot-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add hummingbot-mcp -- uv --directory /path/to/mcp run main.py

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

The configure_server tool should appear in your client's tool list; calling configure_server with no arguments and getting back the current API configuration confirms the connection works.

Troubleshooting

On 'Cannot reach Hummingbot API', verify the API server is running and the URL is accessible
Authentication failures (401) mean wrong credentials; use configure_server to update them
On Mac/Windows Docker, use host.docker.internal instead of localhost
On Linux Docker, add --network host to reach the host's API

Things to try

Once connected, you can ask your AI assistant things like:

Show the current Hummingbot server configuration
Update the Hummingbot API host to 192.168.1.100 and port to 8001
Change the Hummingbot API credentials to username admin and password secure_password
Show my portfolio balances and distribution

Tools 1

configure_server writes

View or update the active Hummingbot API server connection (host, port, credentials); the client automatically reconnects and config persists in ~/.hummingbot_mcp/server.yml

Use cases

Place orders, manage positions, and check balances from Claude or Gemini CLI

Fetch market data such as prices, order books, candles, and funding rates

Deploy and manage Hummingbot bots and controller configuration

Deploy the MCP server together with Hummingbot API in the cloud via Docker Compose

Supported clients

Claude Code

Gemini CLI

Listed from the project's documentation, not tested by this site.

Overview

Hummingbot MCP Server is a Model Context Protocol server that enables Claude and Gemini CLI to interact with the Hummingbot API for automated cryptocurrency trading across multiple exchanges. Maintained by Hummingbot, it exposes tools for account management, order and position handling, market data, funding rates, bot deployment, and controller configuration. It runs via uv locally or Docker, and can be deployed alongside the Hummingbot API using Docker Compose.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 63.3k · Tools 2 Compare with this →

NPM Sentinel MCP Server 79 · B

AI-powered NPM package analysis MCP server

★ 18 · Tools 19 Compare with this →

MartinLoop MCP Server 79 · B

An independent control layer that gives AI coding agents budgets, brakes, and receipts

★ 413 Compare with this →

GitHub MCP Server 76 · B

GitHub's official MCP server for managing repos, issues, PRs, and workflows via natural language

★ 33.7k · Tools 15 Compare with this →

Compare with other MCP servers

Source revision 836f9351d48e Data synced 2026-10-19 Read the FMRS scoring method