{
  "markdown": "# MCP Hummingbot Server\n\nAn MCP (Model Context Protocol) server that enables Claude and Gemini CLI to interact with Hummingbot for automated cryptocurrency trading across multiple exchanges.\n\n## Installation & Configuration\n\n### Option 1: Using uv (Recommended for Development)\n\n1. **Install uv** (if not already installed):\n   ```bash\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n   ```\n\n2. **Clone and install dependencies**:\n   ```bash\n   git clone https://github.com/hummingbot/mcp\n   cd mcp\n   uv sync\n   ```\n\n3. **Create a .env file**:\n   ```bash\n   cp .env.example .env\n   ```\n\n4. **Edit the .env file** with your Hummingbot API credentials:\n   ```env\n   HUMMINGBOT_API_URL=http://localhost:8000\n   HUMMINGBOT_USERNAME=admin\n   HUMMINGBOT_PASSWORD=admin\n   ```\n\n5. **Configure in Claude Code or Gemini CLI**:\n   ```json\n   {\n     \"mcpServers\": {\n       \"hummingbot-mcp\": {\n         \"type\": \"stdio\",\n         \"command\": \"uv\",\n         \"args\": [\n           \"--directory\",\n           \"/path/to/mcp\",\n           \"run\",\n           \"main.py\"\n         ]\n       }\n     }\n   }\n   ```\n   \n   **Note**: Make sure to replace `/path/to/mcp` with the actual path to your MCP directory.\n\n### Option 2: Using Docker (Recommended for Production)\n\n1. **Create a .env file**:\n   ```bash\n   touch .env\n   ```\n\n2. **Edit the .env file** with your Hummingbot API credentials:\n   ```env\n   HUMMINGBOT_API_URL=http://localhost:8000\n   HUMMINGBOT_USERNAME=admin\n   HUMMINGBOT_PASSWORD=admin\n   ```\n\n   **Important**: When running the MCP server in Docker and connecting to a Hummingbot API on your host:\n   - **Linux**: Use `--network host` (see below) to allow the container to access `localhost:8000`\n   - **Mac/Windows**: Change `HUMMINGBOT_API_URL` to `http://host.docker.internal:8000`\n\n3. **Pull the Docker image**:\n   ```bash\n   docker pull hummingbot/hummingbot-mcp:latest\n   ```\n\n4. **Configure in Claude Code or Gemini CLI**:\n\n   **For Linux (using --network host)**:\n   ```json\n   {\n     \"mcpServers\": {\n       \"hummingbot-mcp\": {\n         \"type\": \"stdio\",\n         \"command\": \"docker\",\n         \"args\": [\n           \"run\",\n           \"--rm\",\n           \"-i\",\n           \"--network\",\n           \"host\",\n           \"--env-file\",\n           \"/path/to/mcp/.env\",\n           \"-v\",\n           \"$HOME/.hummingbot_mcp:/root/.hummingbot_mcp\",\n           \"hummingbot/hummingbot-mcp:latest\"\n         ]\n       }\n     }\n   }\n   ```\n\n   **For Mac/Windows**:\n   ```json\n   {\n     \"mcpServers\": {\n       \"hummingbot-mcp\": {\n         \"type\": \"stdio\",\n         \"command\": \"docker\",\n         \"args\": [\n           \"run\",\n           \"--rm\",\n           \"-i\",\n           \"--env-file\",\n           \"/path/to/mcp/.env\",\n           \"-v\",\n           \"$HOME/.hummingbot_mcp:/root/.hummingbot_mcp\",\n           \"hummingbot/hummingbot-mcp:latest\"\n         ]\n       }\n     }\n   }\n   ```\n   (Remember to set `HUMMINGBOT_API_URL=http://host.docker.internal:8000` in your `.env` file)\n\n   **Note**: Make sure to replace `/path/to/mcp` with the actual path to your MCP directory.\n\n### Cloud Deployment with Docker Compose\n\nFor cloud deployment where both Hummingbot API and MCP server run on the same server:\n\n1. **Create a .env file**:\n   ```bash\n   touch .env\n   ```\n\n2. **Edit the .env file** with your Hummingbot API credentials:\n   ```env\n   HUMMINGBOT_API_URL=http://localhost:8000\n   HUMMINGBOT_USERNAME=admin\n   HUMMINGBOT_PASSWORD=admin\n   ```\n\n3. **Create a docker-compose.yml**:\n   ```yaml\n   services:\n     hummingbot-api:\n       container_name: hummingbot-api\n       image: hummingbot/hummingbot-api:latest\n       ports:\n         - \"8000:8000\"\n       volumes:\n         - ./bots:/hummingbot-api/bots\n         - /var/run/docker.sock:/var/run/docker.sock\n       environment:\n         - USERNAME=admin\n         - PASSWORD=admin\n         - BROKER_HOST=emqx\n         - DATABASE_URL=postgresql+asyncpg://hbot:hummingbot-api@postgres:5432/hummingbot_api\n       networks:\n         - emqx-bridge\n       depends_on:\n         - postgres\n   \n     mcp-server:\n       container_name: hummingbot-mcp\n       image: hummingbot/hummingbot-mcp:latest\n       stdin_open: true\n       tty: true\n       env_file:\n         - .env\n       environment:\n         - HUMMINGBOT_API_URL=http://hummingbot-api:8000\n       depends_on:\n         - hummingbot-api\n       networks:\n         - emqx-bridge\n   \n     # Include other services from hummingbot-api docker-compose.yml as needed\n     emqx:\n       container_name: hummingbot-broker\n       image: emqx:5\n       restart: unless-stopped\n       environment:\n         - EMQX_NAME=emqx\n         - EMQX_HOST=node1.emqx.local\n         - EMQX_CLUSTER__DISCOVERY_STRATEGY=static\n         - EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.local]\n         - EMQX_LOADED_PLUGINS=\"emqx_recon,emqx_retainer,emqx_management,emqx_dashboard\"\n       volumes:\n         - emqx-data:/opt/emqx/data\n         - emqx-log:/opt/emqx/log\n         - emqx-etc:/opt/emqx/etc\n       ports:\n         - \"1883:1883\"\n         - \"8883:8883\"\n         - \"8083:8083\"\n         - \"8084:8084\"\n         - \"8081:8081\"\n         - \"18083:18083\"\n         - \"61613:61613\"\n       networks:\n         emqx-bridge:\n           aliases:\n             - node1.emqx.local\n       healthcheck:\n         test: [ \"CMD\", \"/opt/emqx/bin/emqx_ctl\", \"status\" ]\n         interval: 5s\n         timeout: 25s\n         retries: 5\n   \n     postgres:\n       container_name: hummingbot-postgres\n       image: postgres:15\n       restart: unless-stopped\n       environment:\n         - POSTGRES_DB=hummingbot_api\n         - POSTGRES_USER=hbot\n         - POSTGRES_PASSWORD=hummingbot-api\n       volumes:\n         - postgres-data:/var/lib/postgresql/data\n       ports:\n         - \"5432:5432\"\n       networks:\n         - emqx-bridge\n       healthcheck:\n         test: [\"CMD-SHELL\", \"pg_isready -U hbot -d hummingbot_api\"]\n         interval: 10s\n         timeout: 5s\n         retries: 5\n\n   networks:\n     emqx-bridge:\n       driver: bridge\n\n   volumes:\n     emqx-data: { }\n     emqx-log: { }\n     emqx-etc: { }\n     postgres-data: { }\n   ```\n\n4. **Deploy**:\n   ```bash\n   docker compose up -d\n   ```\n\n5. **Configure in Claude Code or Gemini CLI to connect to existing container**:\n   ```json\n   {\n     \"mcpServers\": {\n       \"hummingbot-mcp\": {\n         \"type\": \"stdio\",\n         \"command\": \"docker\",\n         \"args\": [\n           \"exec\",\n           \"-i\",\n           \"hummingbot-mcp\",\n           \"uv\",\n           \"run\",\n           \"main.py\"\n         ]\n       }\n     }\n   }\n   ```\n   \n   **Note**: Replace `hummingbot-mcp` with your actual container name. You can find the container name by running:\n   ```bash\n   docker ps\n   ```\n\n## Server Configuration\n\nOn first run, the server creates a default configuration from environment variables (or uses `http://localhost:8000` with default credentials). Configuration is stored in `~/.hummingbot_mcp/server.yml`.\n\n### Using the configure_server Tool\n\n```\n# Show the current server configuration\nconfigure_server()\n\n# Update the host and port\nconfigure_server(host=\"192.168.1.100\", port=8001)\n\n# Update credentials\nconfigure_server(username=\"admin\", password=\"secure_password\")\n\n# Update everything at once\nconfigure_server(\n    name=\"production\",\n    host=\"prod-server\",\n    port=8000,\n    username=\"admin\",\n    password=\"secure_password\"\n)\n```\n\nOnly the provided parameters are changed; omitted ones keep their current values. The client automatically reconnects after any update.\n\n## Environment Variables\n\nThe following environment variables can be set in your `.env` file for the MCP server:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `HUMMINGBOT_API_URL` | `http://localhost:8000` | Initial default API server URL (used only on first run) |\n| `HUMMINGBOT_USERNAME` | `admin` | Initial username (used only on first run) |\n| `HUMMINGBOT_PASSWORD` | `admin` | Initial password (used only on first run) |\n| `HUMMINGBOT_TIMEOUT` | `30.0` | Connection timeout in seconds |\n| `HUMMINGBOT_MAX_RETRIES` | `3` | Maximum number of retry attempts |\n| `HUMMINGBOT_RETRY_DELAY` | `2.0` | Delay between retries in seconds |\n| `HUMMINGBOT_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |\n\n**Note**: After initial setup, use the `configure_server` tool to update the server connection. Environment variables are only used to create the initial default configuration.\n\n## Requirements\n\n- Python 3.11+\n- Running Hummingbot API server\n- Valid Hummingbot API credentials\n\n## Available Tools\n\nThe MCP server provides tools for:\n\n### Server Management\n- **configure_server**: View or update the active Hummingbot API server connection\n  - No parameters: show current server config\n  - Any parameters: update and reconnect\n  - Configuration persists in `~/.hummingbot_mcp/server.yml`\n\n### Trading & Account Management\n- Account management and connector setup\n- Portfolio balances and distribution\n- Order placement and management\n- Position management\n- Market data (prices, order books, candles)\n- Funding rates\n- Bot deployment and management\n- Controller configuration\n\n## Development\n\nTo run the server in development mode:\n\n```bash\nuv run main.py\n```\n\nTo run tests:\n\n```bash\nuv run pytest\n```\n\n## Troubleshooting\n\nThe MCP server now provides **comprehensive error messages** to help diagnose connection and authentication issues:\n\n### Connection Errors\n\nIf you see error messages like:\n- `❌ Cannot reach Hummingbot API at <url>` - The API server is not running or not accessible\n- `❌ Authentication failed when connecting to Hummingbot API` - Incorrect username or password\n- `❌ Failed to connect to Hummingbot API` - Generic connection failure\n\nThe error messages will include:\n- The exact URL being used\n- Your configured username (password is masked)\n- Specific suggestions on how to fix the issue\n- References to tools like `configure_server`\n\n### Common Solutions\n\n1. **API Not Running**:\n   - Ensure your Hummingbot API server is running\n   - Verify the API is accessible at the configured URL\n\n2. **Wrong Credentials**:\n   - Use `configure_server` tool to update server credentials\n   - Or check your `.env` file configuration\n\n3. **Wrong URL**:\n   - Use `configure_server` tool to update the server URL\n   - For Docker on Mac/Windows, use `host.docker.internal` instead of `localhost`\n\n4. **Docker Network Issues**:\n   - On Linux, use `--network host` in your Docker configuration\n   - On Mac/Windows, use `host.docker.internal:8000` as the API URL\n\n### Error Prevention\n\nThe MCP server will:\n- **Not retry** on authentication failures (401 errors) - it will immediately tell you the credentials are wrong\n- **Retry** on connection failures with helpful messages about what might be wrong\n- **Provide context** about whether you're running in Docker and suggest appropriate fixes\n- **Guide you** to the right tools (`configure_server`) to fix issues\n",
  "bytes": 10866,
  "sha": "1cdc26ade27230e011b32f5e31a9c1ec2bfac2418c448e57aac344ee0ba37503",
  "repo_slug": "hummingbot/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hummingbot_mcp_12209135/readme"
}