LacyLights

LacyLights MCP Server provides an AI-powered interface to design, analyze, and control theatrical lighting through natural language. It connects your AI-assisted workflows with fixture management, cue creation, and live playback, enabling rapid iteration from concept to cue-ready designs.

How to use

You interact with the MCP server via an MCP client or integration that speaks the MCP protocol. Use natural language prompts to generate looks, analyze scripts, create cue sequences, and control live playback. You can translate scripted moments, moods, and blocking into DMX-enabled lighting configurations, then refine those looks with automatic optimization for dramatic impact, energy efficiency, or simplicity. Start by creating or loading a project, define fixtures and channels, generate looks from descriptions, assemble cue sequences, and drive playback during rehearsals or performances. If you run a show, you can start a cue list, advance through cues, jump to a specific cue, or fade to black as needed. You can also adjust looks on the fly to respond to actor blocking or directorial notes.

How to install

Prerequisites: ensure you have Node.js version 18 or newer installed on your system.

Install dependencies and prepare the environment.

How to install

# Install dependencies
npm install

# Copy example environment file and edit with your configuration
cp .env.example .env

How to install

Build and start the server in production mode after configuring your environment.

npm run build
npm start

How to use

Run the MCP server once your backend is ready. You should see confirmation that the RAG service is initialized and the MCP server is running in stdio mode.

Configuration and running

The server relies on environment variables for AI access and backend connectivity. Define OPENAI_API_KEY for AI-powered lighting generation and LACYLIGHTS_GRAPHQL_ENDPOINT to point to your lacylights-go GraphQL backend. Optional ChromaDB settings enable enhanced retrieval-augmented generation.

Example values you would place in your runtime environment (placeholders shown):

Configure the MCP connection for Claude integration

{
  "mcpServers": {
    "lacylights": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/lacylights-mcp/run-mcp.js"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "LACYLIGHTS_GRAPHQL_ENDPOINT": "http://localhost:4000/graphql"
      }
    }
  }
}

Troubleshooting

Common issues include module import errors, GraphQL connection problems, OpenAI API errors, and MCP integration errors in Claude. Ensure you are using the proper node wrapper script, verify backend availability, and confirm your API keys and endpoints are correctly configured.

ChromaDB Setup (Optional - For Enhanced RAG)

To enable persistent vector storage for improved retrieval, you can run ChromaDB locally or via Docker. Update the CHROMA_HOST and CHROMA_PORT values in your environment to enable the RAG features.

Development

The project is organized to support tooling for fixtures, looks, cues, and projects. It includes a core API client, RAG service, and AI-based lighting generation. You can add new tools by implementing them in the designated source directories and wiring them into the MCP server entry point.

Complete example usage notes

A typical workflow guides you through project creation, fixture setup, script analysis, look generation, cue sequence creation, act-level cueing, timing optimization, and live playback control. You can refine positions, color temperatures, and effects to match blocking and costume considerations, then execute the cue lists during rehearsals or performances.

Available tools

list_projects

List all available lighting projects with optional fixture and look counts.

create_project

Create a new lighting project for a production.

get_project_details

Get comprehensive details about a specific project.

delete_project

Delete a project and all associated data (requires confirmation).

qlc_import_guidance

Get information about importing QLC+ (.qxw) files.

get_fixture_inventory

Query available fixtures and their capabilities.

analyze_fixture_capabilities

Deep analysis of fixture capabilities such as color mixing and positioning.

create_fixture_instance

Add a new fixture to a project with manufacturer/model details.

get_channel_map

View DMX channel usage map for a project.

suggest_channel_assignment

Get optimal channel assignments for multiple fixtures.

update_fixture_instance

Modify existing fixture properties.

delete_fixture_instance

Remove a fixture from a project (requires confirmation).

generate_look

AI-powered look generation based on descriptions and context.

analyze_script

Extract lighting cues and suggestions from theatrical scripts.

optimize_look

Optimize looks for goals like energy, impact, or simplicity.

update_look

Update look properties and fixture values.

activate_look

Activate a look by name or ID.

fade_to_black

Fade all lights to black with customizable timing.

get_current_active_look

Query information about the currently active look.

add_fixtures_to_look

Add fixtures to existing looks.

remove_fixtures_from_look

Remove specific fixtures from looks.

get_look_fixture_values

Read current fixture values in a look.

ensure_fixtures_in_look

Ensure fixtures exist with specific values in a look.

update_look_partial

Partial updates with fixture merging for looks.

bulk_update_looks_partial

Batch partial updates across multiple looks with fixture merging.

create_cue_sequence

Build cue sequences from existing looks.

generate_act_cues

Generate complete cue lists for theatrical acts from scripts.

optimize_cue_timing

Optimize cue timing for strategies like dramatic timing.

analyze_cue_structure

Analyze cue lists with recommendations.

update_cue_list

Update cue list metadata.

add_cue_to_list

Add new cues to existing lists.

remove_cue_from_list

Remove cues from lists.

update_cue

Modify individual cue properties.

bulk_update_cues

Update multiple cues simultaneously.

reorder_cues

Reorder cues with new numbering.

get_cue_list_details

Query cues with filtering and sorting.

delete_cue_list

Delete entire cue lists (requires confirmation).

start_cue_list

Begin playing a cue list from any point.

next_cue

Advance to the next cue.

previous_cue

Go back to the previous cue.

go_to_cue

Jump to a specific cue by number or name.

stop_cue_list

Stop the currently playing cue list.

get_cue_list_status

Get playback status and navigation options.

activate_look_from_board

Activate a look from a look board using the board's default fade time.