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.

![License: MIT](LICENSE-MIT) ![Node.js](https://nodejs.org) ![MCP](https://modelcontextprotocol.io)

---

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: ``bash 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: ``json { "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)

| Tool | Description | Modifies State | |------|-------------|---------------| | telegraf-controller_list_configs | List all configurations with metadata | ❌ Read-only | | telegraf-controller_get_config | Get full TOML content of a config | ❌ Read-only | | telegraf-controller_get_config_details | Get config metadata (no TOML) | ❌ Read-only | | telegraf-controller_create_config | Create a new Telegraf configuration | ✅ Creates | | telegraf-controller_update_config | Update name, TOML, or description | ✅ Modifies | | telegraf-controller_delete_config | Delete a configuration | ✅ Deletes | | telegraf-controller_duplicate_config | Clone a configuration | ✅ Creates | | telegraf-controller_bulk_duplicate_configs | Clone multiple configs at once | ✅ Creates | | telegraf-controller_merge_configs | Combine multiple configs into one | ✅ Creates |

Agent Management (6 tools)

| Tool | Description | Modifies State | |------|-------------|---------------| | telegraf-controller_list_agents | List all agents (filterable by status) | ❌ Read-only | | telegraf-controller_get_agent_details | Get full details for one agent | ❌ Read-only | | telegraf-controller_get_agent_summary | Fleet-wide health statistics | ❌ Read-only | | telegraf-controller_delete_agent | Remove an agent from the controller | ✅ Deletes | | telegraf-controller_bulk_delete_agents | Remove multiple agents at once | ✅ Deletes | | telegraf-controller_assign_agent_reporting_rule | Override health threshold for agent | ✅ Modifies |

Label Management (8 tools)

| Tool | Description | Modifies State | |------|-------------|---------------| | telegraf-controller_list_labels | List all labels | ❌ Read-only | | telegraf-controller_get_label | Get label details | ❌ Read-only | | telegraf-controller_create_label | Create a new label | ✅ Creates | | telegraf-controller_update_label | Update label description | ✅ Modifies | | telegraf-controller_delete_label | Delete a label | ✅ Deletes | | telegraf-controller_bulk_delete_labels | Delete multiple labels | ✅ Deletes | | telegraf-controller_assign_label_to_agent | Tag one agent with a label | ✅ Modifies | | telegraf-controller_bulk_assign_labels_to_agents | Tag multiple agents with labels | ✅ Modifies |

Reporting Rules (5 tools)

| Tool | Description | Modifies State | |------|-------------|---------------| | telegraf-controller_list_reporting_rules | List all health threshold rules | ❌ Read-only | | telegraf-controller_get_reporting_rule | Get one rule's details | ❌ Read-only | | telegraf-controller_create_reporting_rule | Define new health threshold | ✅ Creates | | telegraf-controller_update_reporting_rule | Update thresholds | ✅ Modifies | | telegraf-controller_delete_reporting_rule | Remove a rule | ✅ Deletes |

System Tools (3 tools)

| Tool | Description | |------|-------------| | telegraf-controller_health_check | Verify controller is reachable | | telegraf-controller_get_heartbeat_info | Get heartbeat endpoint URL | | telegraf-controller_get_analytics_instance | Get analytics instance ID |

---

MCP Resources

Read-only data URIs available to your AI client:

| URI | Description | |-----|-------------| | telegraf://status | Real-time controller status + agent summary | | telegraf://configs | All configurations (names, IDs, descriptions) | | telegraf://agents | All agents with current health status | | telegraf://reporting-rules | All health threshold rules |

---

MCP Prompts (Guided Workflows)

Pre-built workflows that chain multiple tools together:

| Prompt | Description | |--------|-------------| | check-agent-health | Full fleet health report | | troubleshoot-not-reporting | Diagnose silent agents step-by-step | | create-config-from-template | Guided TOML config creation | | deploy-config-to-agents | Walk through deploying configs | | optimize-reporting-rules | Analyze and improve health thresholds | | agent-fleet-overview | Complete fleet summary |

---

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

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TELEGRAF_CONTROLLER_URL | Yes | http://localhost:8888 | Base URL of Telegraf Controller API |

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/:

| Dashboard | File | Description | |-----------|------|-------------| | IoT Sensor Monitoring | iot-sensors.json | Real-time MQTT sensor data (temp, humidity, pressure, CO2) | | Infrastructure Monitoring | infrastructure.json | CPU, memory, disk, network, Docker metrics | | Controller Events | controller-events.json | Config changes, agent lifecycle, label assignments | | MCP Server Monitoring | telegraf-mcp-monitoring.json | Agent health, config counts, MCP tool activity |

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

| Document | Description | |----------|-------------| | docs/MCP_TOOLS.md | Complete reference for all 27 tools with parameters and examples | | docs/INSTALLATION.md | Step-by-step setup for Claude Desktop, Cline, OpenCode | | docs/GRAFANA_DASHBOARDS.md | All 4 dashboards: panels, queries, import instructions |

---

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: ``bash docker logs telegraf-controller 2>&1 | grep heartbeat ``

MCP server not showing in Claude Desktop

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

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

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

Telegraf Controller MCP Server