Telegraf Controller MCP Server

A Model Context Protocol (MCP) server that gives AI assistants full control over Telegraf Controller — manage agent fleets, configurations, labels, and health rules using natural language.

What This Does

Ask your AI assistant (Claude, Cline, etc.) questions like:

• "Show me all Telegraf agents that haven't reported in the last hour"
• "Create a configuration for MQTT IoT sensor collection and deploy it"
• "Label all production agents and assign them the strict monitoring rule"
• "Merge our CPU, memory, and disk configs into one stack"
• "Which agents are not reporting and why?"

The MCP server translates natural language → 27 API calls → structured answers, all without leaving your chat interface.

Architecture

┌──────────────────────────┐
│   Claude / Cline / etc.  │
└────────────┬─────────────┘
             │ MCP (stdio)
             ▼
┌──────────────────────────┐
│   Telegraf Controller    │
│      MCP Server          │
│  27 tools · 4 resources  │
│  6 guided prompts        │
└────────────┬─────────────┘
             │ HTTP/REST
             ▼
┌──────────────────────────┐
│   Telegraf Controller    │
│   (port 8888)            │
│  Agent mgmt · Configs    │
│  Labels · Health rules   │
└──────────────────────────┘
             │ Heartbeat (port 8889)
             ▼
┌──────────────────────────┐
│   Telegraf Agents        │
│  (IoT, infra, etc.)      │
└──────────────────────────┘

Quick Start

Prerequisites

• Telegraf Controller running (Docker, port 8888)
• Node.js 18+ or Docker
• MCP-compatible client: Claude Desktop, Cline, or OpenCode

1. Start the Telegraf Controller

docker run -d \
  --name telegraf-controller \
  -p 8888:8888 \
  -p 8889:8889 \
  influxdata/telegraf-controller:latest

# Verify
curl http://localhost:8888/health
# → {"status":"healthy","message":"Telegraf Controller is accessible"}

Or use the included Docker Compose:

docker-compose up -d

2. Configure Your MCP Client

#### Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telegraf-controller": {
      "command": "npx",
      "args": ["-y", "@influxdata/telegraf-controller-mcp-server"],
      "env": {
        "TELEGRAF_CONTROLLER_URL": "http://localhost:8888"
      }
    }
  }
}

#### Local install (Node.js)

git clone https://github.com/dburton-influxdata/telegraf-controller-mcp-server.git
cd telegraf-controller-mcp-server
npm install && npm run build

Then in your MCP client config:

{
  "mcpServers": {
    "telegraf-controller": {
      "command": "node",
      "args": ["/absolute/path/to/telegraf-controller-mcp-server/build/index.js"],
      "env": {
        "TELEGRAF_CONTROLLER_URL": "http://localhost:8888"
      }
    }
  }
}

#### Docker

docker run -i --rm --network=host \
  -e TELEGRAF_CONTROLLER_URL=http://localhost:8888 \
  ghcr.io/dburton-influxdata/telegraf-controller-mcp-server:latest

3. Restart Your MCP Client & Test

After restarting Claude Desktop / Cline, ask:

"Check the health of my Telegraf Controller"

You should see the MCP server respond with agent counts, health status, and configuration counts.

Available Tools (27)

Configuration Management (9 tools)

Agent Management (6 tools)

Label Management (8 tools)

Reporting Rules (5 tools)

System Tools (3 tools)

MCP Resources

Read-only data URIs available to your AI client:

MCP Prompts (Guided Workflows)

Pre-built workflows that chain multiple tools together:

Usage Examples

Natural Language

"List all agents that haven't reported in the last 30 minutes"
→ Uses: list_agents(status_filter="not_reporting")

"Create an IoT sensor config for MQTT topics IOT/+/temperature and IOT/+/humidity"
→ Uses: create_config(name=..., toml=...)

"Assign the production label and strict monitoring rule to all US-East agents"
→ Uses: list_agents + list_labels + bulk_assign_labels_to_agents + assign_agent_reporting_rule

"Merge the CPU, memory, and disk configs into one monitoring stack"
→ Uses: list_configs + merge_configs(...)

Slash Commands (Cline / OpenCode)

# Health check
/mcp telegraf-controller_health_check

# List all agents
/mcp telegraf-controller_list_agents limit=100 page=1

# Get unhealthy agents only
/mcp telegraf-controller_list_agents status_filter=not_reporting

# Create a label
/mcp telegraf-controller_create_label description="env:production"

# Create a config
/mcp telegraf-controller_create_config \
  name="iot-sensors" \
  description="MQTT IoT data collector" \
  toml="[agent]\n  interval = \"10s\"\n\n[[inputs.mqtt_consumer]]\n..."

# Create a strict reporting rule
/mcp telegraf-controller_create_reporting_rule \
  name="production-strict" \
  threshold_seconds=300 \
  has_auto_delete=false

Complete Fleet Setup (step-by-step)

1. Check health:
   telegraf-controller_health_check

2. See current state:
   telegraf-controller_get_agent_summary

3. Create environment labels:
   telegraf-controller_create_label description="env:production"
   telegraf-controller_create_label description="location:us-east"
   telegraf-controller_create_label description="type:iot-sensor"

4. Create IoT config:
   telegraf-controller_create_config name="iot-us-east" toml="..."

5. Create strict monitoring rule:
   telegraf-controller_create_reporting_rule name="prod-strict" threshold_seconds=300

6. Assign labels to agents:
   telegraf-controller_bulk_assign_labels_to_agents agent_ids="..." label_ids="..."

7. Assign reporting rule:
   telegraf-controller_assign_agent_reporting_rule agent_id="..." rule_id="..."

Configuration

Environment Variables

MCP Client Config Examples

See the examples/ directory:

• examples/claude-desktop-local.json — Claude Desktop, local Node.js
• examples/claude-desktop-npx.json — Claude Desktop, npx
• examples/claude-desktop-docker.json — Claude Desktop, Docker

Grafana Dashboards

Four pre-built Grafana dashboards are included in grafana/dashboards/:

Import Dashboards

# Install Grafana (if not running)
docker run -d -p 3001:3000 --name grafana grafana/grafana:latest

# Import via Grafana UI
# 1. http://localhost:3001 → Dashboards → Import
# 2. Upload JSON files from grafana/dashboards/

# Or import via API
for f in grafana/dashboards/*.json; do
  curl -s -X POST http://admin:admin@localhost:3001/api/dashboards/import \
    -H "Content-Type: application/json" \
    -d "{\"dashboard\": $(cat $f), \"overwrite\": true, \"folderId\": 0}"
  echo " → Imported: $f"
done

See docs/GRAFANA_DASHBOARDS.md for full panel descriptions and queries.

Documentation

Project Structure

telegraf-controller-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── configs.ts        # Configuration management tools
│   │   ├── agents.ts         # Agent management tools
│   │   └── reporting.ts      # Reporting rules tools
│   ├── resources/
│   │   └── index.ts          # 4 MCP resources
│   ├── prompts/
│   │   └── index.ts          # 6 guided prompts
│   └── utils/
│       ├── client.ts         # Telegraf Controller API client
│       └── validation.ts     # Input validation helpers
├── examples/
│   ├── claude-desktop-local.json
│   ├── claude-desktop-npx.json
│   └── claude-desktop-docker.json
├── grafana/
│   └── dashboards/
│       ├── iot-sensors.json
│       ├── infrastructure.json
│       ├── controller-events.json
│       └── telegraf-mcp-monitoring.json
├── docs/
│   ├── MCP_TOOLS.md          # All 27 tools reference
│   ├── INSTALLATION.md       # Setup guide
│   └── GRAFANA_DASHBOARDS.md # Dashboard reference
├── context/                  # Telegraf documentation context files
├── Dockerfile
├── docker-compose.yml
├── package.json
└── tsconfig.json

Development

Build from Source

git clone https://github.com/dburton-influxdata/telegraf-controller-mcp-server.git
cd telegraf-controller-mcp-server
npm install
npm run build

Test with MCP Inspector

npm run inspector
# Opens browser-based MCP inspector at http://localhost:5173

Test Manually

# Initialize the MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | TELEGRAF_CONTROLLER_URL=http://localhost:8888 node build/index.js

# List all tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | TELEGRAF_CONTROLLER_URL=http://localhost:8888 node build/index.js

Docker Build

docker build -t telegraf-controller-mcp-server:dev .

# Test Docker image
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | docker run -i --rm --network=host \
      -e TELEGRAF_CONTROLLER_URL=http://localhost:8888 \
      telegraf-controller-mcp-server:dev

Troubleshooting

"Cannot connect to Telegraf Controller"

# Check controller is running
curl http://localhost:8888/health

# Check from Docker (if MCP runs in Docker)
curl http://host.docker.internal:8888/health

"No agents found"

Agents must send heartbeats to the Controller. Add to any Telegraf config:

[[outputs.http]]
  url = "http://localhost:8889/agents/heartbeat"
  method = "POST"
  data_format = "json"
  [outputs.http.headers]
    Content-Type = "application/json"

Verify heartbeats are arriving:

docker logs telegraf-controller 2>&1 | grep heartbeat

MCP server not showing in Claude Desktop

1. Verify the path to build/index.js is absolute (not relative)
2. Check JSON config syntax (no trailing commas)
3. Check Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\

1. Restart Claude Desktop completely

Related Resources

• Telegraf Documentation
• InfluxDB3 Documentation
• Model Context Protocol Spec
• Telegraf Controller MCP Demo — Full IoT demo with sensor simulation, Grafana, and InfluxDB3
• InfluxDB3 MCP Server — MCP server for InfluxDB v3

License

MIT — see LICENSE

Built by the InfluxData community · [Report an issue](https://github.com/dburton-influxdata/telegraf-controller-mcp-server/issues)