The LacyLights MCP Server provides AI-powered theatrical lighting design and control through natural language interactions.
Project Management: Create, list, retrieve details, and delete lighting projects, including QLC+ file imports.
Fixture Management: Add, update, and remove fixtures; analyze capabilities; manage DMX channel assignments and universes with optimal configuration suggestions.
Scene Creation & Optimization: Generate scenes from natural language descriptions or script analysis; optimize for energy efficiency, color accuracy, dramatic impact, or technical simplicity; update existing scenes with new fixture settings.
Cue Sequence Management: Build cue sequences from scenes; generate cue suggestions from script analysis; optimize timing with smooth transitions or dramatic strategies; analyze cue structure; add, remove, update, and reorder cues.
Live Performance Control: Start, stop, navigate, and jump to cues during performances; make real-time adjustments and updates.
Advanced Features: Script analysis for lighting extraction, collaborative workflows, partial scene updates, fixture merging, and comprehensive project analytics.
Supports running ChromaDB via Docker for persistent vector storage and advanced RAG capabilities when analyzing theatrical scripts
Connects to a GraphQL endpoint to access the LacyLights backend for fixture and scene management
Uses OpenAI's API for AI-powered lighting generation, script analysis, and intelligent scene creation based on artistic intent and lighting design principles
LacyLights MCP Server
An MCP (Model Context Protocol) server that provides AI-powered theatrical lighting design capabilities for the LacyLights system. This server enables AI assistants to create, manage, and control professional theatrical lighting designs through natural language interactions.
What is LacyLights MCP?
LacyLights MCP is an intelligent lighting control interface that bridges the gap between creative vision and technical execution. It allows lighting designers, directors, and technicians to:
Design lighting scenes using natural language descriptions
Analyze theatrical scripts to automatically generate lighting cues
Manage DMX fixtures from various manufacturers
Create and run cue sequences for theatrical performances
Optimize lighting designs for dramatic impact or energy efficiency
The system uses AI to understand artistic intent and translate it into precise DMX values for real-world lighting fixtures.
Complete Function Reference
Project Management
list_projects
- List all available lighting projects with optional fixture/scene countscreate_project
- Create a new lighting project for a productionget_project_details
- Get comprehensive details about a specific projectdelete_project
- Delete a project and all associated data (requires confirmation)qlc_import_guidance
- Get information about importing QLC+ (.qxw) files
Fixture Management
get_fixture_inventory
- Query available fixtures and their capabilitiesanalyze_fixture_capabilities
- Deep analysis of fixture capabilities (color mixing, positioning, effects)create_fixture_instance
- Add a new fixture to a project with manufacturer/model detailsget_channel_map
- View DMX channel usage map for a projectsuggest_channel_assignment
- Get optimal channel assignments for multiple fixturesupdate_fixture_instance
- Modify existing fixture propertiesdelete_fixture_instance
- Remove a fixture from a project (requires confirmation)
Scene Creation & Management
generate_scene
- AI-powered scene generation based on descriptions and contextanalyze_script
- Extract lighting cues and suggestions from theatrical scriptsoptimize_scene
- Optimize scenes for various goals (energy, impact, simplicity)update_scene
- Update scene properties and fixture valuesactivate_scene
- Activate a scene by name or IDfade_to_black
- Fade all lights to black with customizable timingget_current_active_scene
- Get information about the currently active scene
Advanced Scene Operations
add_fixtures_to_scene
- Add fixtures to existing scenesremove_fixtures_from_scene
- Remove specific fixtures from scenesget_scene_fixture_values
- Read current fixture values in a sceneensure_fixtures_in_scene
- Ensure fixtures exist with specific valuesupdate_scene_partial
- Partial scene updates with fixture merging
Cue Sequence Management
create_cue_sequence
- Build cue sequences from existing scenesgenerate_act_cues
- Generate complete cue lists for theatrical actsoptimize_cue_timing
- Optimize cue timing for various strategiesanalyze_cue_structure
- Analyze cue lists with recommendations
Cue List Operations
update_cue_list
- Update cue list metadataadd_cue_to_list
- Add new cues to existing listsremove_cue_from_list
- Remove cues from listsupdate_cue
- Modify individual cue propertiesbulk_update_cues
- Update multiple cues simultaneouslyreorder_cues
- Reorder cues with new numberingget_cue_list_details
- Query cues with filtering and sortingdelete_cue_list
- Delete entire cue lists (requires confirmation)
Cue Playback Control
start_cue_list
- Begin playing a cue list from any pointnext_cue
- Advance to the next cueprevious_cue
- Go back to the previous cuego_to_cue
- Jump to a specific cue by number or namestop_cue_list
- Stop the currently playing cue listget_cue_list_status
- Get playback status and navigation options
Installation
Install dependencies:
Set up environment variables:
Build the project:
Configuration
Required Environment Variables
OPENAI_API_KEY
- OpenAI API key for AI-powered lighting generationLACYLIGHTS_GRAPHQL_ENDPOINT
- GraphQL endpoint for your lacylights-node backend (default: http://localhost:4000/graphql)
Optional Environment Variables
CHROMA_HOST
- ChromaDB host for enhanced RAG functionality (default: localhost)CHROMA_PORT
- ChromaDB port (default: 8000)
Running the Server
Make sure your lacylights-node
backend is running first, then:
You should see:
Integration with Claude
Add this server to your Claude configuration:
Important:
Use the absolute path to
run-mcp.js
in your configurationIf the above doesn't work, find your Node.js path with:
which node
The wrapper script ensures proper CommonJS module loading
Complete Example: Lighting Design for Macbeth
Here's a comprehensive example showing how a lighting designer would use LacyLights MCP to create a complete lighting design for Shakespeare's Macbeth:
Step 1: Create the Project
Step 2: Set Up Fixtures
Step 3: Analyze the Script
Step 4: Generate Key Scenes
Step 5: Create Cue Sequences
Step 6: Generate Act Cues with Script Analysis
Step 7: Optimize for Performance
Step 8: Create Special Effect Sequences
Step 9: Run the Show
During performance, the stage manager can use:
Step 10: Make Live Adjustments
Advanced Usage Examples
Script-Driven Design Workflow
Multi-Universe Setup
Collaborative Design Process
AI-Powered Features
Intelligent Script Analysis
Extracts explicit lighting cues from stage directions
Identifies implicit lighting needs from dialogue and action
Suggests atmospheric lighting based on dramatic context
Recognizes standard theatrical conventions (sunrise, sunset, storms)
Context-Aware Scene Generation
Understands theatrical lighting principles
Applies color theory for emotional impact
Considers fixture capabilities and positions
Generates DMX values that respect real-world constraints
Adaptive Optimization
Energy Efficiency: Reduces power consumption while maintaining artistic intent
Dramatic Impact: Enhances contrast and focus for maximum effect
Technical Simplicity: Simplifies programming for easier operation
Color Accuracy: Optimizes for true color rendering
Troubleshooting
Common Issues
Module import errors
Ensure Node.js version is 18+ as specified in package.json
Use the
run-mcp.js
wrapper script, notdist/index.js
directly
GraphQL connection errors
Verify your
lacylights-node
backend is running on port 4000Check the
LACYLIGHTS_GRAPHQL_ENDPOINT
environment variable
OpenAI API errors
Ensure your
OPENAI_API_KEY
is set in the.env
fileVerify the API key has access to GPT-4
MCP connection errors in Claude
Use the full absolute path in your Claude configuration
Restart Claude after updating the MCP configuration
Check Claude's logs for detailed error messages
"Unexpected token ?" error
Update your config to use the full path to Node.js 14+
On macOS with Homebrew:
"command": "/opt/homebrew/bin/node"
On other systems, find your node path with:
which node
ChromaDB Setup (Optional - For Enhanced RAG)
The MCP server works out of the box with in-memory pattern storage. For persistent vector storage and more sophisticated pattern matching:
Option 1: Docker (Recommended)
Option 2: Local Installation
Then update your .env
file:
Integration with LacyLights Ecosystem
This MCP server is part of the complete LacyLights system:
lacylights-node - Backend GraphQL API for fixture and scene management
lacylights-fe - Web frontend for manual control and visualization
lacylights-mcp - AI interface for intelligent automation
The MCP server enhances the existing system with:
Natural language control
Intelligent scene generation
Script analysis capabilities
Automated cue creation
Performance optimization
Development
Project Structure
Adding New Tools
Create tool implementation in appropriate file under
src/tools/
Add tool definition to
src/index.ts
in theListToolsRequestSchema
handlerAdd tool handler in the
CallToolRequestSchema
handlerUpdate this README with tool documentation
Testing
License
MIT
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Provides AI-powered theatrical lighting design capabilities for the LacyLights system, allowing users to generate lighting scenes, analyze scripts, manage cues, and optimize lighting effects based on artistic intent.
- What is LacyLights MCP?
- Complete Function Reference
- Installation
- Configuration
- Running the Server
- Integration with Claude
- Complete Example: Lighting Design for Macbeth
- Advanced Usage Examples
- AI-Powered Features
- Troubleshooting
- ChromaDB Setup (Optional - For Enhanced RAG)
- Integration with LacyLights Ecosystem
- Development
- License
Related MCP Servers
- AsecurityAlicenseAqualityProvides LLM Agents with AI-powered mentorship for code review, design critique, writing feedback, and brainstorming using the Deepseek API, enabling enhanced output in various development and strategic planning tasks.Last updated -32Apache 2.0
- AsecurityFlicenseAqualityEnables interaction with lightning addresses and common lightning tools via your LLM, providing Lightning Network functionality through natural language.Last updated -3121
- -securityFlicense-qualityProvides tools to interact with RunwayML and Luma AI APIs for video and image generation, including text-to-video, image-to-video, prompt enhancement, and management of generations.Last updated -11
- -securityFlicense-qualityA modular system for building and orchestrating AI applications through microservices, featuring LLM interactions, Jupyter notebook execution, and visual workflow capabilities.