Nanoleaf MCP Server

🚀 Nanoleaf MCP Server

A Model Context Protocol (MCP) server for controlling Nanoleaf smart lights. It provides tools to control your Nanoleaf devices through Warp terminal or any MCP-compatible client.

✨ Features

• 🔍 Auto-discovery: Automatically discover Nanoleaf devices on your network.
• 🔗 Direct IP connection: Connect to specific devices by their IP addresses.
• 🔐 Authorization support: Ensure secure device pairing with authorization.
• 💡 Full control: Control lights, brightness, colors, and effects comprehensively.
• 🐳 Dockerized: Facilitate easy deployment with Docker.
• 🖥️ Warp terminal integration: Integrate seamlessly with Warp terminal.

🛠️ Available Tools

• get_nanoleaf_info: Retrieve detailed device information.
• turn_on_nanoleaf / turn_off_nanoleaf: Control the power state of the device.
• set_brightness: Adjust the brightness level (0 - 100).
• set_color: Set the color using hue (0 - 360) and saturation (0 - 100).
• set_effect: Apply various lighting effects.
• get_effects: List all available lighting effects.
• discover_nanoleaf: Discover Nanoleaf devices on the network.
• connect_to_ip: Connect to a specific IP address.
• authorize_nanoleaf: Authorize the device in pairing mode.

🚀 Quick Start

Automated Setup (Recommended)

For a hassle - free setup, use the provided setup script:

./setup.sh

This script will perform the following steps:

1. Build the Docker image.
2. Scan the network for Nanoleaf devices.
3. Assist you in obtaining the authorization token.
4. Create all necessary configuration files.
5. Test the setup.
6. Generate your Warp configuration.

Manual Setup

Prerequisites

• Docker installed on your system.
• Nanoleaf device(s) connected to your network.
• Warp terminal (optional, for MCP integration).

Step 1: Clone and Build

git clone <repository-url>
cd nanoleaf-mcp-server
docker build -t nanoleaf-mcp-server-nanoleaf-mcp-server .

Step 2: Find Your Nanoleaf Device

Option A: Auto - discovery

docker run --rm -i --network=host nanoleaf-mcp-server echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "discover_nanoleaf", "arguments": {}}}'

Option B: Manual IP scan

# Scan your network for devices responding on Nanoleaf port
nmap -p 16021 192.168.1.0/24

Option C: Check router admin panel for connected devices

Step 3: Get Authorization Token

1. Put your Nanoleaf device in pairing mode:
   • Hold the power button on your Nanoleaf device for 5 - 7 seconds.
   • Look for the pairing indicator (usually a flashing light).
2. Get the auth token immediately (within 30 seconds):

# Replace 192.168.1.100 with your device's IP
curl -X POST http://192.168.1.100:16021/api/v1/new

You should receive a response like:

{"auth_token":"YourAuthTokenHere123456789"}

Step 4: Configure Environment

Create a .env file in the project directory:

NANOLEAF_IP=192.168.1.100
NANOLEAF_AUTH_TOKEN=YourAuthTokenHere123456789
NANOLEAF_PORT=16021
NANOLEAF_PROTOCOL=http

Step 5: Test Your Setup

# Test with environment variables
docker run --rm -i --network=host --env-file .env nanoleaf-mcp-server echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_nanoleaf_info", "arguments": {}}}'

If successful, you'll see detailed information about your Nanoleaf device!

Step 6: Run Examples (Optional)

Test all functionality with the example script:

./examples.sh

This will demonstrate all available features, including turning lights on/off, changing colors, and applying effects.

💻 Working Example

Here's a complete working example with real values (replace with your own):

1. Device discovered at: <DEVICE_IP>:16021
2. Auth token obtained: <AUTH_TOKEN>
3. Warp configuration:

{
  "mcpServers": {
    "nanoleaf": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "NANOLEAF_IP=<DEVICE_IP>",
        "-e", "NANOLEAF_AUTH_TOKEN=<AUTH_TOKEN>",
        "-e", "NANOLEAF_PORT=16021",
        "-e", "NANOLEAF_PROTOCOL=http",
        "nanoleaf-mcp-server-nanoleaf-mcp-server"
      ],
      "env": {}
    }
  }
}

4. Test command:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "set_effect", "arguments": {"effect": "Cyberpunk 2077"}}}' | docker run --rm -i --network=host -e NANOLEAF_IP=<DEVICE_IP> -e NANOLEAF_AUTH_TOKEN=<AUTH_TOKEN> nanoleaf-mcp-server-nanoleaf-mcp-server

💻 Warp Terminal Integration

Add to Warp MCP Configuration

Add the following to your Warp MCP servers configuration (replace the values with your actual device IP and auth token):

{
  "mcpServers": {
    "nanoleaf": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "NANOLEAF_IP=192.168.1.100",
        "-e", "NANOLEAF_AUTH_TOKEN=YourAuthTokenHere123456789",
        "-e", "NANOLEAF_PORT=16021",
        "-e", "NANOLEAF_PROTOCOL=http",
        "nanoleaf-mcp-server-nanoleaf-mcp-server"
      ],
      "env": {}
    }
  }
}

Important:

• Replace 192.168.1.100 with your Nanoleaf device's IP address.
• Replace YourAuthTokenHere123456789 with your actual auth token.
• Make sure you've built the Docker image with the tag nanoleaf-mcp-server-nanoleaf-mcp-server.

Alternative Configuration (if path issues occur)

If you encounter path - related issues, you can use this alternative approach:

{
  "mcpServers": {
    "nanoleaf": {
      "command": "bash",
      "args": ["-c", "cd /path/to/nanoleaf-mcp-server && docker run --rm -i --network=host --env-file .env nanoleaf-mcp-server-nanoleaf-mcp-server"],
      "env": {}
    }
  }
}

Using in Warp

Once configured, you can use the Nanoleaf tools directly in Warp:

• Ask to turn lights on/off.
• Change brightness and colors.
• Apply cool effects like "Northern Lights" or "Cyberpunk".
• Get device information.

💻 Manual Usage Examples

Turn lights on/off

# Turn on
curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":true}}'

# Turn off  
curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":false}}'

Set brightness

curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"brightness":{"value":50}}'

Apply an effect

curl -X PUT http://your-ip:16021/api/v1/your-token/effects \
  -H "Content-Type: application/json" \
  -d '{"select":"Northern Lights"}'

⚙️ Troubleshooting

Device Not Found

• Ensure the device is on the same network.
• Check firewall settings.
• Try manual IP scanning: nmap -p 16021 192.168.1.0/24

Authorization Failed

• The device must be in pairing mode (hold the power button for 5 - 7 seconds).
• Pairing mode only lasts about 30 seconds.
• Make sure no other devices are already controlling it.

Connection Issues

• Verify the IP address is correct.
• Check if the device uses HTTPS (some newer models).
• Ensure Docker has network access (--network=host).

Environment Variables Not Working

• Check if the .env file exists and has correct values.
• Verify that the Docker command includes --env-file .env.
• Make sure file paths are absolute in the Warp config.

Warp Terminal Issues

"The system cannot find the path specified" error

• Use the direct environment variable configuration instead of --env-file.
• Make sure your Docker image tag matches exactly: nanoleaf-mcp-server-nanoleaf-mcp-server.
• Try the alternative bash configuration if path issues persist.

MCP server not responding in Warp

• Verify that the Docker image is built with the correct tag.
• Check that your IP address and auth token are correct in the configuration.
• Test the Docker command manually first:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_nanoleaf_info", "arguments": {}}}' | docker run --rm -i --network=host -e NANOLEAF_IP=your-ip -e NANOLEAF_AUTH_TOKEN=your-token nanoleaf-mcp-server-nanoleaf-mcp-server

"MCP server exited" in logs

• This usually indicates a configuration issue.
• Check that all environment variables are properly set.
• Ensure the Docker image exists: docker images | grep nanoleaf

📱 Device Compatibility

Tested with:

• Nanoleaf Canvas
• Nanoleaf Light Panels
• Nanoleaf Hexagons

It should work with most Nanoleaf devices that support the v1 API.

🤝 Contributing

Feel free to submit issues, feature requests, or pull requests!

📄 License

MIT License - see the LICENSE file for details.