Nanoleaf

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

- 🔍Auto-discoveryof Nanoleaf devices on your network
- 🔗Direct IP connectionfor specific device targeting
- 🔐Authorization supportfor secure device pairing
- 💡Full controlof lights, brightness, colors, and effects
- 🐳Dockerizedfor easy deployment
- 🖥️Warp terminal integration
- 🔒Security-auditeddependencies with regular vulnerability checks

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

For the easiest setup experience, use the included setup script:
- Build the Docker image
- Scan for Nanoleaf devices on your network
- Help you get the authorization token
- Create all configuration files
- Test the setup
- Generate your Warp configuration

- Docker installed on your system
- Nanoleaf device(s) on your network
- Warp terminal (optional, for MCP integration)

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

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

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

Put your Nanoleaf device in pairing mode:

- Hold the power button on your Nanoleaf device for 5-7 seconds
- Look for pairing indicator (usually a flashing light)

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

{"auth_token":"YourAuthTokenHere123456789"}

Create a.envfile in the project directory:

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

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

Test all functionality with the example script:

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

Here's a complete working example with real values (replace with your own):
- Device discovered at:<DEVICE_IP>:16021
- Auth token obtained:<AUTH_TOKEN>
- 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": {} } } }

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

Add this 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": {} } } }

- Replace192.168.1.100with your Nanoleaf device's IP address
- ReplaceYourAuthTokenHere123456789with your actual auth token
- Make sure you've built the Docker image with tagnanoleaf-mcp-server-nanoleaf-mcp-server

Alternative Configuration (if path issues occur)

If you encounter path-related issues, you can also 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": {} } } }

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

# 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}}'

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

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

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

- Device must be in pairing mode (hold power button 5-7 seconds)
- Pairing mode only lasts ~30 seconds
- Make sure no other devices are already controlling it

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

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

"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

- Verify 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

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

- Nanoleaf Canvas
- Nanoleaf Light Panels
- Nanoleaf Hexagons

Should work with most Nanoleaf devices that support the v1 API.

- Dependency Audit Report- Detailed security audit and dependency update information
- Setup Scripts- Automated setup and testing scripts included
- Docker Configuration- Containerized deployment for easy management

Native macOS HomeKit integration for AI assistants via Model Context Protocol