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)

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:

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\
4. 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