influxdb-mcp-server/QUICKSTART.md

# Quick Start Guide

Get up and running with the InfluxDB MCP Server in 5 minutes.

## Prerequisites Check

Before starting, ensure you have:
- [ ] Node.js 18+ installed (`node --version`)
- [ ] InfluxDB v2 running (local or remote)
- [ ] An InfluxDB authentication token

## Step 1: Install Dependencies

```bash
cd /Users/felix/Nextcloud/AI/projects/influxdb-mcp-server
npm install
npm run build
```

## Step 2: Configure Environment

Create a `.env` file:

```bash
cp .env.example .env
```

Edit `.env` with your values:

```env
INFLUX_URL=http://localhost:8086
INFLUX_TOKEN=your_actual_token_here
INFLUX_ORG=your_org_name
```

### Getting Your InfluxDB Token

1. Open InfluxDB UI: http://localhost:8086
2. Click **Data** → **API Tokens**
3. Click **Generate API Token** → **All Access Token**
4. Copy the token
5. Paste it into your `.env` file

## Step 3: Test the Server

Test that the server can connect to InfluxDB:

```bash
INFLUX_URL=http://localhost:8086 \
INFLUX_TOKEN=your_token \
INFLUX_ORG=your_org \
node dist/index.js
```

You should see:
```
Successfully connected to InfluxDB
Server: influxdb (version x.y.z)
Status: pass
InfluxDB MCP Server running on stdio
```

Press `Ctrl+C` to stop.

## Step 4: Configure Claude Desktop

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "influxdb": {
      "command": "node",
      "args": ["/Users/felix/Nextcloud/AI/projects/influxdb-mcp-server/dist/index.js"],
      "env": {
        "INFLUX_URL": "http://localhost:8086",
        "INFLUX_TOKEN": "your_token_here",
        "INFLUX_ORG": "your_org_name"
      }
    }
  }
}
```

### Linux

Edit `~/.config/Claude/claude_desktop_config.json` (same format as macOS).

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json` (same format as macOS).

**Important:** Replace `/Users/felix/Nextcloud/AI/projects/influxdb-mcp-server` with the actual absolute path to your installation.

## Step 5: Restart Claude Desktop

1. Completely quit Claude Desktop
2. Start Claude Desktop again
3. Look for the 🔌 icon or MCP indicator

## Step 6: Test with Claude

Try these prompts:

### Test 1: Check Connection
```
Is my InfluxDB server healthy?
```

Expected: Claude will read the health resource and tell you the server status.

### Test 2: List Buckets
```
What buckets are in my InfluxDB instance?
```

Expected: Claude will list all your buckets.

### Test 3: Write Test Data
```
Write a test temperature reading of 22.5 to a bucket called "test-bucket"
(use my default organization)
```

Expected: Claude will write data using line protocol.

### Test 4: Query Data
```
Show me the last 10 minutes of data from "test-bucket"
```

Expected: Claude will execute a Flux query and return results.

## Troubleshooting

### "Connection refused" error

**Problem:** Can't connect to InfluxDB

**Solutions:**
1. Verify InfluxDB is running: `curl http://localhost:8086/health`
2. Check the URL in your config
3. Check firewall settings

### "Unauthorized" error

**Problem:** Authentication failed

**Solutions:**
1. Verify your token is correct
2. Check token hasn't expired
3. Ensure token has necessary permissions
4. Try generating a new All Access Token

### "Organization not found" error

**Problem:** Wrong organization name

**Solutions:**
1. In Claude, ask: "What organizations are available?"
2. Update `INFLUX_ORG` with the correct name
3. Restart Claude Desktop

### Claude doesn't see the server

**Problem:** MCP server not loading

**Solutions:**
1. Verify the path in `claude_desktop_config.json` is absolute
2. Check that `dist/index.js` exists and is executable
3. Look at Claude Desktop logs:
   - macOS: `~/Library/Logs/Claude/`
   - Windows: `%APPDATA%\Claude\logs\`
4. Ensure JSON syntax is correct (no trailing commas)
5. Restart Claude Desktop completely

### "Module not found" error

**Problem:** Dependencies not installed

**Solution:**
```bash
cd /Users/felix/Nextcloud/AI/projects/influxdb-mcp-server
npm install
npm run build
```

## Next Steps

Now that you're set up:

1. **Read EXAMPLES.md** for real-world usage patterns
2. **Explore your data** by asking Claude to analyze your buckets
3. **Create dashboards** by having Claude query and format data
4. **Set up monitoring** by writing periodic data from your applications

## Common First Tasks

### Explore Your Data
```
What measurements are in my "telegraf" bucket?
```

### Analyze Recent Metrics
```
Show me the average CPU usage across all servers in the last hour
```

### Create a New Bucket
```
Create a bucket called "application-metrics" with a 90-day retention policy
```

### Write Application Metrics
```
Write the following metrics to "application-metrics":
- API response time: 125ms for /users endpoint
- API response time: 89ms for /posts endpoint
```

### Generate Reports
```
Create a daily summary of temperature readings from all sensors
```

## Pro Tips

1. **Start with simple queries** and build up complexity
2. **Use natural language** - Claude understands context
3. **Ask for explanations** if you're learning Flux
4. **Iterate on queries** - refine as you go
5. **Let Claude help with schema** - ask what data is available first

## Getting Help

- **Documentation**: See README.md for full documentation
- **Examples**: See EXAMPLES.md for detailed usage examples
- **InfluxDB Docs**: https://docs.influxdata.com/influxdb/v2/
- **Flux Guide**: https://docs.influxdata.com/flux/v0/

## Development Mode

If you're developing or modifying the server:

```bash
# Watch mode (rebuilds on changes)
npm run watch

# In another terminal, test changes
node dist/index.js
```

Remember to restart Claude Desktop after rebuilding to see changes.

## Security Checklist

- [ ] Never commit `.env` file to version control
- [ ] Use least-privilege tokens (not always All Access)
- [ ] Use HTTPS for remote InfluxDB instances
- [ ] Rotate tokens periodically
- [ ] Keep dependencies updated: `npm update`

## Success Checklist

You're ready when:
- [ ] Server connects to InfluxDB successfully
- [ ] Claude Desktop shows the MCP server loaded
- [ ] You can check server health via Claude
- [ ] You can list buckets via Claude
- [ ] You can write test data via Claude
- [ ] You can query data via Claude

Congratulations! You now have a working InfluxDB MCP Server. Start exploring your time-series data with Claude!