MCP Server

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. The Apache Iggy MCP Server is an implementation of the MCP protocol for the message streaming infrastructure. It is built using the rmcp crate and supports both stdio and HTTP transports.

Getting started

To start the MCP server, simply run cargo run --bin iggy-mcp.

The docker image is available, and can be fetched via docker pull apache/iggy-mcp.

Configuration

The minimal viable configuration requires at least the Iggy credentials, used to create the TCP connection to the running Iggy server that the MCP server talks to. You can choose between HTTP (the default) and STDIO transports (e.g. for the local usage with tools such as Claude Desktop choose stdio).

transport = "http" # http (default) or stdio are supported

[iggy]
address = "localhost:8090" # TCP address of the Iggy server
username = "iggy"
password = "iggy"
# token = "secret" # Personal Access Token (PAT) can be used instead of username and password
# token = "file:/run/secrets/iggy_pat" # PAT can also be read from a file
# consumer = "iggy-mcp" # Optional consumer name

[iggy.tls] # Optional TLS configuration for the Iggy TCP connection
enabled = false
ca_file = "path/to/ca.pem"
domain = "" # Optional domain for TLS connection

[http] # Optional HTTP API configuration
address = "127.0.0.1:8082"
path = "/mcp"

[http.cors] # Optional CORS configuration for HTTP API
enabled = false
allowed_methods = ["GET", "POST", "PUT", "DELETE"]
allowed_origins = ["*"]
allowed_headers = ["content-type"]
exposed_headers = [""]
allow_credentials = false
allow_private_network = false

[http.tls] # Optional TLS configuration for HTTP API
enabled = false
cert_file = "core/certs/iggy_cert.pem"
key_file = "core/certs/iggy_key.pem"

[permissions]
create = true
read = true
update = true
delete = true

[telemetry] # Optional OpenTelemetry integration
enabled = false
service_name = "iggy-mcp"

[telemetry.logs]
transport = "grpc" # grpc or http
endpoint = "http://localhost:4317"

[telemetry.traces]
transport = "grpc" # grpc or http
endpoint = "http://localhost:4317"

The configuration file must be in the toml format. The path to the configuration can be overridden by IGGY_MCP_CONFIG_PATH environment variable. Each setting can also be overridden by using the following convention IGGY_MCP_<SECTION>_<KEY> e.g. IGGY_MCP_IGGY_USERNAME, IGGY_MCP_HTTP_ADDRESS and so on. Environment variables can also be loaded from a dotenv file: point IGGY_MCP_ENV_PATH at the file, otherwise a .env file in the current working directory is loaded automatically.

The token value can be either a literal PAT or a file: reference such as token = "file:/run/secrets/iggy_pat", in which case the token is read from the given file (~ is expanded to the home directory).

Available tools

The MCP server exposes 40+ tools covering the full Iggy API:

Server

Streams

Topics

Partitions & Segments

Messages

Consumer Groups

Consumer Offsets

Users & Access Tokens

Permissions

The [permissions] section provides a first layer of access control, checked before any request is forwarded to the Iggy server. This lets you restrict the MCP server to read-only operations, for example:

[permissions]
create = false
read = true
update = false
delete = false

On top of this, the Iggy user account used by the MCP server has its own granular permissions. For production use, create a dedicated user with the minimum required permissions.

Claude Desktop integration

Here's the example configuration to be used with Claude Desktop:

{
  "mcpServers": {
    "iggy": {
      "command": "/path/to/iggy-mcp",
      "args": [],
      "env": {
        "IGGY_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Docker

Run the MCP server as a container:

docker run -e IGGY_MCP_TRANSPORT=http \
  -e IGGY_MCP_HTTP_ADDRESS=0.0.0.0:8082 \
  -e IGGY_MCP_IGGY_ADDRESS=iggy-server:8090 \
  -e IGGY_MCP_IGGY_USERNAME=iggy \
  -e IGGY_MCP_IGGY_PASSWORD=iggy \
  -p 8082:8082 \
  apache/iggy-mcp

The default HTTP address is 127.0.0.1:8082, which inside a container is unreachable from the outside, so IGGY_MCP_HTTP_ADDRESS=0.0.0.0:8082 is required for the published port to work.

Systemd integration

Build with the systemd cargo feature to enable systemd readiness and watchdog notifications:

cargo build --bin iggy-mcp --release --features iggy-mcp/systemd

The MCP server then behaves the same way the Iggy server does under systemd.