Halton IoT MCP Server

An MCP (Model Context Protocol) server for the Halton IoT Data API. This server allows AI assistants to interact with Halton's IoT systems, retrieving sensor data, system information, and more.

🚀 Quick Start

One-Command Setup

npx @haltongroup/halton-iot-mcp-setup

This will prompt for your API token (from api.halton.io) and configure VS Code automatically.

Or Manual Setup (VS Code UI)

1. Cmd/Ctrl+Shift+P → "MCP: Add Server"
2. Select Docker as the type
3. Enter image: ghcr.io/haltongroup/haltoniotmcp:latest
4. Add env var: HALTON_API_TOKEN = your token from api.halton.io

Features

• 🔌 System Discovery: List and inspect IoT systems
• 📊 Time Series Data: Get aggregated sensor data (hourly default)
• 🔍 Variable Search: Search for specific sensors/variables

Available Tools

| Tool | Description | |------|-------------| | get_all_systems | Get information about all accessible IoT systems | | get_systems | Get information about specific systems | | get_system_variables | List all variables (sensors) for systems | | search_variables | Search for variables by keywords | | get_aggregate_data | Get aggregated time series data (min/max/avg, hourly default) | | get_aggregate_data_multiple | Get aggregated data for multiple variables | | get_last_value | Get the most recent value for a variable | | get_last_values_multiple | Get recent values for multiple variables |

Example Questions

Once connected, ask GitHub Copilot:

• "What Halton systems do I have access to?"
• "Show me the airflow data for the last 24 hours"
• "What's the current UV lamp status?"
• "List all sensors on Hood 1"

Alternative Setup Methods

Per-Project Config

Create .vscode/mcp.json in your project:

{
  "servers": {
    "halton-iot": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HALTON_API_TOKEN", "ghcr.io/haltongroup/haltoniotmcp:latest"],
      "env": {
        "HALTON_API_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "halton-iot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HALTON_API_TOKEN", "ghcr.io/haltongroup/haltoniotmcp:latest"],
      "env": {
        "HALTON_API_TOKEN": "your-token-here"
      }
    }
  }
}

Docker MCP Gateway

See DOCKER_MCP.md for Docker MCP Gateway setup.

Development

Build and run with Docker:

# Build the Docker image
docker build -t halton-iot-mcp .

# Run directly
docker run -e HALTON_API_TOKEN="your-token" halton-iot-mcp

Configure with Docker MCP:

1. Build and tag the image:

docker build -t halton-iot-mcp:latest .

2. Create a local catalog entry (~/.docker/mcp/catalogs/custom.yaml):

servers:
  halton-iot:
    name: "Halton IoT"
    description: "Access Halton IoT systems and sensor data"
    image: halton-iot-mcp:latest
    secrets:
      - name: HALTON_API_TOKEN
        description: "Halton IoT API Token"

3. Enable the server:

docker mcp catalog add custom ~/.docker/mcp/catalogs/custom.yaml
docker mcp server enable halton-iot

4. Configure the secret:

docker mcp secret set halton-iot HALTON_API_TOKEN "your-token"

5. Run the gateway:

docker mcp gateway run

Example Queries

Once connected, you can ask the AI assistant things like:

• "List all available IoT systems"
• "What sensors are available on system FI02728?"
• "Get the temperature readings for the last 24 hours from system US02145"
• "Show me the airflow data aggregated by hour"
• "What was the last recorded value for ConnectionStatus?"

API Reference

This MCP server wraps the Halton IoT API v2. For detailed API documentation, refer to:

• Swagger UI: https://api.halton.io/index.html
• OpenAPI Spec: http://api.halton.io/v2/swagger.json

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (rebuild on changes)
npm run dev

License

MIT