How do I use Telegraf Controller MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Telegraf Controller MCP Server Check the health of my Telegraf Controller" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Telegraf Controller MCP Server

by dburton-influxdata

Overview Schema Related Servers Score Discussions

TypeScript

Remote

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 Node.js MCP

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.

Related MCP server: Grafana MCP Server

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

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

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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dburton-influxdata/telegraf-controller-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Telegraf Controller MCP Server

What This Does

Architecture

Quick Start

Prerequisites

1. Start the Telegraf Controller

2. Configure Your MCP Client

Claude Desktop

Local install (Node.js)

Docker

3. Restart Your MCP Client & Test

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

MCP Prompts (Guided Workflows)

Usage Examples

Natural Language

Slash Commands (Cline / OpenCode)

Complete Fleet Setup (step-by-step)

Configuration

Environment Variables

MCP Client Config Examples

Grafana Dashboards

Import Dashboards

Documentation

Project Structure

Development

Build from Source

Test with MCP Inspector

Test Manually

Docker Build

Troubleshooting

"Cannot connect to Telegraf Controller"

"No agents found"

MCP server not showing in Claude Desktop

Related Resources

License

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API