GitHub - tuannvm/haproxy-mcp-server: A Model Context Protocol (MCP) server for HAProxy implemented in Go, leveraging HAProxy Runtime API and mcp-go. (original) (raw)

HAProxy MCP Server

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

Overview

The HAProxy MCP Server provides a standardized way for LLMs to interact with HAProxy's runtime API via the Model Context Protocol (MCP). This enables LLMs to perform HAProxy administration tasks, monitor server status, manage backend servers, and analyze traffic patterns, all through natural language interfaces.

Features

• Full HAProxy Runtime API Support: Comprehensive coverage of HAProxy's runtime API commands
• Context-Aware Operations: All operations support proper timeout and cancellation handling
• Stats Page Integration: Support for HAProxy's web-based statistics page for enhanced metrics and visualization
• Secure Authentication: Support for secure connections to HAProxy runtime API
• Multiple Transport Options: Supports both stdio and HTTP transports for flexibility in different environments
• Enterprise Ready: Designed for production use in enterprise environments
• Docker Support: Pre-built Docker images for easy deployment

Installation

Homebrew

Add the tap

brew tap tuannvm/tap

Install the package

brew install haproxy-mcp-server

From Binary

Download the latest binary for your platform from the releases page.

Using Go

go install github.com/tuannvm/haproxy-mcp-server/cmd/server@latest

Using Docker

docker pull ghcr.io/tuannvm/haproxy-mcp-server:latest docker run -it --rm
-e HAPROXY_HOST=your-haproxy-host
-e HAPROXY_PORT=9999
ghcr.io/tuannvm/haproxy-mcp-server:latest

MCP Integration

To use this server with MCP-compatible LLMs, configure the assistant with the following connection details:

HAProxy Runtime API over TCP4:

{ "mcpServers": { "haproxy": { "command": "haproxy-mcp-server", "env": { "HAPROXY_HOST": "localhost", "HAPROXY_PORT": "9999", "HAPROXY_RUNTIME_MODE": "tcp4", "HAPROXY_RUNTIME_TIMEOUT": "10", "MCP_TRANSPORT": "stdio" } } } }

HAProxy Runtime API over Unix Socket:

{ "mcpServers": { "haproxy": { "command": "haproxy-mcp-server", "env": { "HAPROXY_RUNTIME_MODE": "unix", "HAPROXY_RUNTIME_SOCKET": "/var/run/haproxy/admin.sock", "HAPROXY_RUNTIME_TIMEOUT": "10", "MCP_TRANSPORT": "stdio" } } } }

HAProxy with Stats Page Support:

{ "mcpServers": { "haproxy": { "command": "haproxy-mcp-server", "env": { "HAPROXY_STATS_ENABLED": "true", "HAPROXY_STATS_URL": "http://localhost:8404/stats", "HAPROXY_STATS_TIMEOUT": "5", "MCP_TRANSPORT": "stdio" } } } }

When using only the stats page functionality, there's no need to define Runtime API parameters like host and port. You can use both Runtime API and Stats Page simultaneously for complementary capabilities, or use only one of them based on your environment's constraints.

Note: For detailed instructions on how to configure HAProxy to expose the Runtime API and Statistics page, see the HAProxy Configuration Guide.

Available MCP Tools

The HAProxy MCP Server exposes tools that map directly to HAProxy's Runtime API commands, organized into the following categories:

• Statistics & Process Info: Retrieve statistics, server information, and manage counters
• Topology Discovery: List frontends, backends, server states, and configuration details
• Dynamic Pool Management: Add, remove, enable/disable servers and adjust their properties
• Session Control: View and manage active sessions
• Maps & ACLs: Manage HAProxy maps and ACL files
• Health Checks & Agents: Control health checks and agent-based monitoring
• Miscellaneous: View errors, run echo tests, and get help information

For a complete list of all supported tools with their inputs, outputs, and corresponding HAProxy Runtime API commands, see the tools.md documentation.

Configuration

The server can be configured using the following environment variables:

Note: You can use the Runtime API (TCP4 or Unix socket mode), the Stats API, or both simultaneously. At least one must be properly configured for the server to function.

Security Considerations

• Authentication: Connect to HAProxy's Runtime API using secure methods
• Network Security: When using TCP4 mode, restrict connectivity to the Runtime API port
• Unix Socket Permissions: When using Unix socket mode, ensure proper socket file permissions
• Input Validation: All inputs are validated to prevent injection attacks

For comprehensive security best practices and configuration examples, see the HAProxy Configuration Guide.

Development

Testing

Run all tests

go test ./...

Run tests excluding integration tests

go test -short ./...

Run integration tests with specific HAProxy instance

export HAPROXY_HOST="your-haproxy-host" export HAPROXY_PORT="9999" go test ./internal/haproxy -v -run Test

You can test the HAProxy MCP server locally in several ways:

Direct CLI Testing

Build and run the server directly with environment variables:

Build the server

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

Option 1: Test with TCP connection mode

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

Option 2: Test with Unix socket mode

HAPROXY_RUNTIME_MODE=unix HAPROXY_RUNTIME_SOCKET=/path/to/haproxy.sock HAPROXY_RUNTIME_TIMEOUT=10 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

Option 3: Test with Stats page integration

HAPROXY_STATS_ENABLED=true HAPROXY_STATS_URL="http://localhost:8404/stats" HAPROXY_STATS_TIMEOUT=5 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

Option 4: Test with both Runtime API and Stats page

HAPROXY_HOST= HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 HAPROXY_STATS_ENABLED=true HAPROXY_STATS_URL="http://localhost:8404/stats" HAPROXY_STATS_TIMEOUT=5 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

Test Individual MCP Tools

You can test specific MCP tools with JSON-RPC calls:

Test show_info tool

echo '{"jsonrpc":"2.0","id":1,"method":"callTool","params":{"name":"show_info","arguments":{}}}' | HAPROXY_HOST= HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 LOG_LEVEL=debug ./bin/haproxy-mcp-server

Test show_stat tool

echo '{"jsonrpc":"2.0","id":2,"method":"callTool","params":{"name":"show_stat","arguments":{"filter":""}}}' | HAPROXY_HOST= HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 LOG_LEVEL=debug ./bin/haproxy-mcp-server

Technical Implementation

The HAProxy MCP Server includes several technical improvements designed for reliability and robustness:

• Context-Aware Operations: All API calls support context-based timeout and cancellation, allowing graceful termination of long-running operations.
• Fallback Mechanisms: Automatic fallback to socat if direct connection fails, ensuring compatibility across different HAProxy deployments.
• Unified Socket Handling: Common code for both TCP and Unix socket connections, reducing duplication and improving maintainability.
• Resilient Connection Management: Dynamic buffer management for large responses and proper resource cleanup with deadline handling.
• Comprehensive Error Handling: Structured error handling and logging for easier troubleshooting.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.