The Scenic MCP server enables remote control of Scenic GUI applications via TCP connection with these capabilities:
Connection Management: Establish and test connectivity with
connect_scenic
and check status withget_scenic_status
Keyboard Input: Send text and special keys (enter, escape, tab, arrows, F1-F12) with
send_keys
, including modifier key combinations (ctrl, shift, alt, cmd/meta)Mouse Control: Move cursor to precise coordinates with
send_mouse_move
and simulate clicks withsend_mouse_click
using left, right, or middle buttonsViewport Inspection: Retrieve details of what's currently displayed on the Scenic application with
inspect_viewport
Provides integration with Scenic (an Elixir UI framework), enabling AI-driven automation and testing for Scenic applications through a TCP server that exposes app state and allows interaction with UI elements.
Uses Node.js to implement the MCP server component that bridges between the Elixir TCP server and AI assistants, enabling the control of Scenic applications.
Scenic MCP
Model Context Protocol (MCP) server for Scenic GUI applications
Version: 1.0.0
Enable AI assistants to interact with Scenic GUI applications through keyboard input, mouse control, and visual feedback. Perfect for automated testing, AI-driven development workflows, and accessibility tools.
Features
š¹ Keyboard Input - Send text and special keys with modifier support (Ctrl, Shift, Alt, Cmd)
š±ļø Mouse Control - Move cursor and click at specific coordinates
šø Visual Feedback - Inspect viewport structure and capture screenshots
š¤ MCP Integration - Works with Claude Desktop, Claude Code, and other MCP clients
Quick Start
1. Add to your Scenic app's mix.exs
Note this is still not actually published to hex so you need to clone it and add it as a local dep for now.
2. Configure your viewport and driver
Scenic MCP requires named viewport and driver processes. Update your supervision tree:
Note that name
here defines the atom which will become the registered process name for the ViewPort and Driver processes. We need to know this in order to find the pid of this process in order to interact with the ViewPort, and our solution was to look for this specific name main_viewport
so you need to set this in your config as above for ScenicMCP to work.
Viewport name: :main_viewport
Driver name: :scenic_driver
Optional: Custom process names
If you need different process names, configure them:
3. Install TypeScript dependencies
4. Configure Claude Code or Claude Desktop
Using Claude Code CLI (Recommended)
Manual Configuration
Edit ~/.claude.json
:
Optional: Tidewave MCP Configuration
Tidewave provides runtime introspection for Elixir/Phoenix apps (logs, SQL queries, code evaluation, docs). If your project includes Tidewave (Flamelex/Quillex do), add this to the same project config:
5. Start your Scenic app
You should see:
Usage
Available Tools
Connection & Status
connect_scenic
- Establish connection to running Scenic appget_scenic_status
- Check connection status and server info
User Input
send_keys
- Send keyboard input (text, special keys, modifiers)send_mouse_move
- Move cursor to coordinatessend_mouse_click
- Click at coordinates (left/right/middle button)
Visual Feedback
inspect_viewport
- Get text description of viewport structuretake_screenshot
- Capture PNG screenshot (path or base64)
Examples
Text Input
Special Keys
Keyboard Shortcuts
Mouse Control
Visual Inspection
Architecture
How It Works
TypeScript MCP Server handles MCP protocol via stdio
TCP Bridge maintains persistent connection to Elixir
Elixir GenServer receives JSON commands over TCP
Tool Handlers interact with Scenic viewport and driver
Driver injects input events into your application
Configuration
Available Options
Multiple Scenic Apps
If you're running multiple Scenic apps, configure unique ports:
Connect to specific ports:
Development
Build TypeScript
Bundle for Distribution
Run Tests
Project Structure
Troubleshooting
Port Already in Use
Error: Port 9999 is already in use!
Solution: Configure a different port in your config.exs:
Cannot Find Viewport
Error: Unable to find Scenic viewport process ':main_viewport'
Solutions:
Ensure your viewport is named:
name: :main_viewport
in your Scenic configOr configure the expected name:
config :scenic_mcp, viewport_name: :your_name
Verify your Scenic app is running:
Process.whereis(:main_viewport)
Cannot Find Driver
Error: Unable to find Scenic driver process ':scenic_driver'
Solutions:
Ensure your driver is named:
name: :scenic_driver
in your driver configOr configure the expected name:
config :scenic_mcp, driver_name: :your_name
Check driver started:
Process.whereis(:scenic_driver)
Connection Timeout
Error: Command timeout after 5000ms
Solutions:
Check if Scenic app is running
Verify correct port:
connect_scenic({ port: YOUR_PORT })
Check firewall settings (should allow localhost:9999)
Tests Failing
If tests fail with connection errors:
Ensure no other apps are using test ports (9996-9998)
Run tests with:
mix test --trace
for detailed outputCheck that
scenic_driver_local
dependency is properly compiled
Security Considerations
ā ļø Important Security Notes:
Scenic MCP binds to
localhost
only - not accessible from external networksNo authentication - anyone with local access can control your app
Intended for development and testing environments only
Do not expose the TCP port (9999) to untrusted networks
Do not use in production without additional security measures
See SECURITY.md for detailed security guidelines.
Integration Guide
See docs/INTEGRATION.md for step-by-step integration instructions, including:
Adding Scenic MCP to existing applications
Common patterns and best practices
Testing strategies
Example implementations
API Reference
Error Handling
All tool functions return consistent error structures:
Success responses include a status
field:
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Add tests for new functionality
Ensure
mix test
passesSubmit a pull request
Requirements
Elixir ~> 1.14
Erlang/OTP 24+
Node.js >= 18.0
Scenic ~> 0.11
Claude Desktop or Claude Code (for MCP client)
License
MIT License - see LICENSE for details
Related Projects
Scenic - 2D UI framework for Elixir
MCP - Model Context Protocol specification
Tidewave - Elixir/Phoenix MCP tools
Changelog
See CHANGELOG.md for version history.
Support
Report bugs: GitHub Issues
Documentation: This README and docs/
Examples: See examples/ directory
Made with ā¤ļø for the Elixir and Scenic communities
A Model Context Protocol server that enables AI-driven automation and testing of Scenic Elixir applications through a TCP connection.
Related MCP Servers
- -securityFlicense-qualityA demonstration implementation of the Model Context Protocol server that facilitates communication between AI models and external tools while maintaining context awareness.Last updated -
- -securityFlicense-qualityImplements a Model Context Protocol server that provides context from CucumberStudio to AI assistants, enabling them to fetch data and generate or modify test scenarios, features, and other CucumberStudio resources.Last updated -
- -securityFlicense-qualityA Model Context Protocol server that enables integration with the TESS API, allowing users to list and manage agents, execute agents with custom messages, and manage files through natural language interfaces.Last updated -
- AsecurityFlicenseAqualityA Model Context Protocol server that enables generating and executing Elisp code in a running Emacs process, allowing AI assistants to control and interact with Emacs.Last updated -230