haproxy

A Model Context Protocol (MCP) server for HAProxy implemented in Go, leveraging HAProxy Runtime API and mcp-go.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio tuannvm-haproxy-mcp-server haproxy-mcp-server \
  --env MCP_PORT="Port for HTTP transport (when using http)" \
  --env LOG_LEVEL="Logging level (debug/info/warn/error)" \
  --env HAPROXY_HOST="Host of the HAProxy instance (TCP4 mode only)" \
  --env HAPROXY_PORT="Port for the HAProxy Runtime API (TCP4 mode only)" \
  --env MCP_TRANSPORT="MCP transport method (stdio/http)" \
  --env HAPROXY_STATS_URL="URL to HAProxy stats page (e.g., http://localhost:8404/stats)" \
  --env HAPROXY_RUNTIME_URL="Direct URL to Runtime API (optional, overrides other runtime settings)" \
  --env HAPROXY_RUNTIME_MODE="Connection mode: "tcp4" or "unix"" \
  --env HAPROXY_STATS_ENABLED="Enable HAProxy stats page support" \
  --env HAPROXY_STATS_TIMEOUT="Timeout for stats page operations in seconds" \
  --env HAPROXY_RUNTIME_SOCKET="Socket path (Unix mode only)" \
  --env HAPROXY_RUNTIME_TIMEOUT="Timeout for runtime API operations in seconds"

How to use

This HAProxy MCP Server provides a standardized interface to HAProxy's Runtime API via the Model Context Protocol (MCP). It exposes a suite of tools that map directly to HAProxy Runtime API commands, organized into categories such as statistics and process info, topology discovery, dynamic pool management, session control, maps and ACLs, health checks and agents, and miscellaneous tasks. You can connect to the server using MCP-compatible clients over stdio or HTTP (depending on the transport you configure). The README includes example MCP configurations for running with TCP4, Unix socket mode, and optional Stats Page support, and notes that you can combine Runtime API access with Stats Page capabilities or use just one. With this server running, you can issue natural-language-like requests to perform actions such as querying stats, listing backends, enabling or disabling pool members, managing servers, and retrieving configuration details, all mediated by the MCP layer and translated into HAProxy Runtime API commands.

How to install

Prerequisites: Go installed and configured in your environment (the project is a Go-based MCP server), Git to clone the repository, and optionally Docker or Homebrew if you prefer alternative installation paths. You will build or download the binary, then run the server with the appropriate environment variables to connect to your HAProxy instance.

Steps:

Install prerequisites

Go: https://golang.org/doc/install
git: https://git-scm.com/downloads

Build the server from source (example):

go build -o haproxy-mcp-server ./cmd/server

Run the server with necessary environment variables (example TCP4 runtime):

HAPROXY_HOST=localhost HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 MCP_TRANSPORT=stdio LOG_LEVEL=info ./haproxy-mcp-server

Alternatively, run via Docker (example):

docker run -it --rm \
  -e HAPROXY_HOST=localhost \
  -e HAPROXY_PORT=9999 \
  -e HAPROXY_RUNTIME_MODE=tcp4 \
  -e MCP_TRANSPORT=stdio \
  ghcr.io/tuannvm/haproxy-mcp-server:latest

For Homebrew-based installation (if you prefer):

brew tap tuannvm/tap
brew install haproxy-mcp-server

Verify installation by checking logs or connecting a MCP client to the configured transport.

Additional notes

Tips:

You can enable either the TCP4 Runtime API, the Unix socket Runtime API, the Stats page, or any combination, depending on your HAProxy deployment and security requirements. At least one runtime access method should be properly configured for the MCP server to function.
If you use the Stats Page, ensure HAPROXY_STATS_ENABLED is set to true and provide a valid HAPROXY_STATS_URL. The MCP transport can remain stdio or switch to http if you enable HTTP transport.
Be mindful of security considerations: restrict access to the Runtime API port or Unix socket, and use secure transport when possible.
The server exposes a wide range of tools mapped to HAProxy Runtime API commands. Review tools.md in the repository for a complete list of inputs, outputs, and command mappings.
When running in environments with network constraints, using Unix socket mode can reduce exposure compared to TCP4.