# Telegraf Controller MCP Server

> A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants full control over [Telegraf Controller](https://docs.influxdata.com/telegraf/) — manage agent fleets, configurations, labels, and health rules using natural language.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE-MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](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](https://claude.ai/download), [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev), or [OpenCode](https://opencode.ai)

### 1. Start the Telegraf Controller

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

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

#### Local install (Node.js)

```bash
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

```bash
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)

```bash
# 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/`](examples/) directory:

- [`examples/claude-desktop-local.json`](examples/claude-desktop-local.json) — Claude Desktop, local Node.js
- [`examples/claude-desktop-npx.json`](examples/claude-desktop-npx.json) — Claude Desktop, npx
- [`examples/claude-desktop-docker.json`](examples/claude-desktop-docker.json) — Claude Desktop, Docker

---

## Grafana Dashboards

Four pre-built Grafana dashboards are included in [`grafana/dashboards/`](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

```bash
# 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](docs/GRAFANA_DASHBOARDS.md) for full panel descriptions and queries.

---

## Documentation

| Document | Description |
|----------|-------------|
| [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | Complete reference for all 27 tools with parameters and examples |
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Step-by-step setup for Claude Desktop, Cline, OpenCode |
| [docs/GRAFANA_DASHBOARDS.md](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

```bash
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

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

### Test Manually

```bash
# 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

```bash
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"

```bash
# 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:

```toml
[[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

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](https://docs.influxdata.com/telegraf/)
- [InfluxDB3 Documentation](https://docs.influxdata.com/influxdb3/)
- [Model Context Protocol Spec](https://modelcontextprotocol.io/)
- [Telegraf Controller MCP Demo](https://github.com/dburton-influxdata/telegraf-controller-mcp-demo) — Full IoT demo with sensor simulation, Grafana, and InfluxDB3
- [InfluxDB3 MCP Server](https://github.com/influxdata/influxdb3_mcp_server) — MCP server for InfluxDB v3

---

## License

MIT — see [LICENSE](LICENSE)

---

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