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

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

Step 2: Configure Environment

Create a .env file:

cp .env.example .env

Edit .env with your values:

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:

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:

{
  "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:

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:

# 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!