kapua-mcp-server

An MCP server that connects AI assistants to Eclipse Kapua and Eurotech Everyware Cloud IoT platforms — enabling natural-language device management, telemetry exploration, and fleet diagnostics.

Why use this?

Instead of navigating dashboards, writing curl commands, or learning the Kapua REST API, you can manage your IoT fleet through conversation:

You: "Show me all disconnected devices" Assistant: calls kapua-devices-list with status=DISCONNECTED — lists 3 offline gateways

You: "What happened to gateway-07 in the last hour?" Assistant: calls kapua-device-events-list — shows a disconnect event 42 minutes ago

You: "Show me its current configuration" Assistant: calls kapua-device-configurations-read — displays all component configs

You: "Roll it back to the previous snapshot" Assistant: calls kapua-device-snapshot-rollback — triggers rollback successfully

This turns multi-step diagnostic workflows into a guided conversation without context-switching away from your IDE or terminal.

Quick Start

1. Configure credentials

Create a .venv file in the project root. Choose one of the two authentication methods:

Username/password (default):

cat <<'EOF' > .venv
KAPUA_API_ENDPOINT=https://kapua.example.com/api
KAPUA_USER=my-user
KAPUA_PASSWORD=my-password
EOF

API key (recommended for production):

cat <<'EOF' > .venv
KAPUA_API_ENDPOINT=https://kapua.example.com/api
KAPUA_AUTH_METHOD=apikey
KAPUA_API_KEY=my-api-key
EOF

2. Build and run

make build
./bin/kapua-mcp-server          # stdio transport (default)
./bin/kapua-mcp-server -http    # HTTP transport on localhost:8000

Or without building: go run ./cmd/server

Docker

docker build -t kapua-mcp-server .

docker run --rm \
  -e KAPUA_API_ENDPOINT=https://kapua.example.com/api \
  -e KAPUA_AUTH_METHOD=apikey \
  -e KAPUA_API_KEY=my-api-key \
  -p 8000:8000 \
  kapua-mcp-server

The image is based on gcr.io/distroless/base-debian12:nonroot and supports multi-architecture builds (amd64/arm64).

Configuration

Settings can be provided as environment variables or in a .venv file (one KEY=VALUE per line). Environment variables take precedence.

MCP Client Setup

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kapua-mcp-server": {
      "command": "/path/to/kapua-mcp-server",
      "args": [],
      "env": {
        "KAPUA_API_ENDPOINT": "https://kapua.example.com/api",
        "KAPUA_USER": "my-user",
        "KAPUA_PASSWORD": "my-password"
      }
    }
  }
}

... View full README on GitHub