Initial commit
This commit is contained in:
Felix Zösch
275
QUICKSTART.md
Normal file
275
QUICKSTART.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user