ddc-ci-control-bridge
v1.0.5TypeScript
Multi-protocol bridge for DDC/CI monitor control with MCP and MQTT support
0/weekUpdated 3 months agoMITUnpacked: 179.3 MB
Published by defozo
npm install ddc-ci-control-bridgeDDC/CI Control Bridge
  
Multi-protocol server for DDC/CI monitor control with MCP and MQTT support.
Features
- DDC/CI Monitor Control: Read and write VCP codes to control monitor brightness, contrast, input source, and more
- Model Context Protocol (MCP): Server with resources and tools for AI/agent integration
- MQTT Client: Connect to any MQTT broker for IoT/automation platforms
- Home Assistant auto-discovery support
- Generic MQTT pub/sub for custom integrations
- Cross-Platform: Works on Windows, Linux, and macOS
- Dual Distribution: Available as standalone executable or npm package
Quick Start
$3
Option 1: NPM Package (Global)
``bash`
npm install -g ddc-ci-control-bridge
ddc-ci-bridge
Option 2: NPX (No Install)
`bash`
npx ddc-ci-control-bridge
Option 3: Standalone Executable
Download the binary for your platform from GitHub Releases:
- Windows: ddc-ci-bridge-windows.exe
- Linux:
- macOS:
Then run it:
Windows:
`cmdRun directly
.\ddc-ci-bridge-windows.exe
Or with environment variables
set DDC_API_KEY=your-secret-key
set MQTT_ENABLED=true
set MQTT_HOST=192.168.1.100
.\ddc-ci-bridge-windows.exe
`
Linux/macOS:
bash
Make executable
chmod +x ddc-ci-bridge-linux # or ddc-ci-bridge-macosRun directly
./ddc-ci-bridge-linuxOr with environment variables
DDC_API_KEY=your-secret-key MQTT_ENABLED=true MQTT_HOST=192.168.1.100 ./ddc-ci-bridge-linux
`Using with MCP Clients:
Configure your MCP client to use the executable path:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "/path/to/ddc-ci-bridge-linux",
"args": [],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`$3
Choose between Local (stdio) or Remote (HTTP) setup depending on your needs:
- Local Setup: Run MCP server on the same machine as your monitors (recommended for most users)
- Remote Setup: Run MCP server on a monitor-connected machine, access from other devices
---
#### 🖥️ Local Setup (stdio - Same Machine)
Use this if your MCP client is on the same machine as your monitors.
Install in Cursor (Local)
Go to:
→ Cursor Settings → MCP → Add new global MCP server
Or paste the following configuration into your
file:`json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false",
"MQTT_HOST": "localhost",
"MQTT_PORT": "1883"
}
}
}
}
`Optional MQTT: Set
and configure MQTT_HOST to your MQTT broker IP for automation platform integration.
Install in VS Code (Local)
Add this to your VS Code MCP config file:
`json
"mcp": {
"servers": {
"ddc-ci-bridge": {
"type": "stdio",
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Claude Desktop (Local)
Open Claude Desktop developer settings and edit your
file:`json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Claude Code (Local)
Run this command:
sh
claude mcp add ddc-ci-bridge -- npx -y ddc-ci-control-bridge
`
Install in Windsurf (Local)
Add this to your Windsurf MCP config file:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Cline (Local)
Add this to your Cline MCP configuration:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Zed (Local)
Add this to your Zed
:`json
{
"context_servers": {
"DDC/CI Bridge": {
"source": "custom",
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Roo Code (Local)
Add this to your Roo Code MCP configuration:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Augment Code (Local)
Option A: Using the UI
1. Click the hamburger menu
2. Select Settings
3. Navigate to Tools section
4. Click + Add MCP button
5. Enter command:
6. Name: DDC/CI Bridge
7. Click AddOption B: Manual Configuration
Add to
:`json
"augment.advanced": {
"mcpServers": [
{
"name": "ddc-ci-bridge",
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
]
}
`
Install in JetBrains AI Assistant (Local)
1. Go to
→ Tools → AI Assistant → Model Context Protocol (MCP)
2. Click
3. Select As JSON from the dropdown
4. Add this configuration:json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`5. Click
to save changes
Install in Warp (Local)
1. Navigate
Settings → AI → Manage MCP servers
2. Click button
3. Paste this configuration:`json
{
"DDC/CI Bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"FASTMCP_API_KEY": "your-api-key-here",
"MQTT_ENABLED": "false"
},
"working_directory": null,
"start_on_launch": true
}
}
`4. Click
Install in OpenAI Codex (Local)
Add to your Codex MCP configuration:
toml
[mcp_servers.ddc-ci-bridge]
command = "npx"
args = ["-y", "ddc-ci-control-bridge"][mcp_servers.ddc-ci-bridge.env]
MQTT_ENABLED = "false"
`Windows Users: Use full paths if you encounter timeout errors:
toml
[mcp_servers.ddc-ci-bridge]
command = "cmd"
args = ["/c", "npx", "-y", "ddc-ci-control-bridge"]
startup_timeout_ms = 20_000[mcp_servers.ddc-ci-bridge.env]
SystemRoot = "C:\\Windows"
FASTMCP_API_KEY = "your-api-key-here"
MQTT_ENABLED = "false"
`
Install in LM Studio (Local)
1. Navigate to
(right side) → Install → Edit mcp.json
2. Add this configuration:json
{
"mcpServers": {
"DDC/CI Bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`3. Click
4. Toggle the MCP server on/off from the right side panel
Install in Qodo Gen (Local)
1. Open Qodo Gen chat panel in VSCode or IntelliJ
2. Click Connect more tools
3. Click + Add new MCP
4. Add this configuration:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Install in Perplexity Desktop (Local)
1. Navigate
→ Settings
2. Select
3. Click
4. Select
5. Enter Server Name: DDC/CI Bridge
6. Paste this JSON:json
{
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"FASTMCP_API_KEY": "your-api-key-here",
"MQTT_ENABLED": "false"
}
}
`7. Click
Install in Kiro (Local)
1. Navigate
→ MCP Servers
2. Click button
3. Paste this configuration:`json
{
"mcpServers": {
"DDC/CI Bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
},
"disabled": false,
"autoApprove": []
}
}
}
`4. Click
Install in BoltAI (Local)
1. Open Settings → Plugins
2. Enter this JSON:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`3. Save and restart if needed
Install in Zencoder (Local)
1. Go to Zencoder menu (...)
2. Select Agent tools
3. Click Add custom MCP
4. Add name and server configuration:
json
{
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"FASTMCP_API_KEY": "your-api-key-here",
"MQTT_ENABLED": "false"
}
}
`5. Click Install
Install in Amazon Q Developer CLI (Local)
Add to your Amazon Q configuration:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "npx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Using Bun or Deno
Bun:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "bunx",
"args": ["-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`Deno:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "deno",
"args": [
"run",
"--allow-env",
"--allow-net",
"npm:ddc-ci-control-bridge"
],
"env": {
"MQTT_ENABLED": "false"
}
}
}
}
`
Windows-Specific Configuration
On Windows, use this format (example with Cline):
json
{
"mcpServers": {
"ddc-ci-bridge": {
"command": "cmd",
"args": ["/c", "npx", "-y", "ddc-ci-control-bridge"],
"env": {
"MQTT_ENABLED": "false"
},
"disabled": false,
"autoApprove": []
}
}
}
`---
#### 🌐 Remote Setup (HTTP - Different Machines)
Use this if you want to access monitor controls from a different machine on your network.
Step 1: Set up the MCP Server on Monitor-Connected Machine
1. On the machine with monitors, create a
file:`bash
DDC_API_KEY=your-secure-random-api-key-here
MCP_TRANSPORT=sse
MCP_PORT=8000Optional: Enable MQTT for automation platforms
MQTT_ENABLED=false
MQTT_HOST=localhost
MQTT_PORT=1883
`2. Start the server:
bash
npm install -g ddc-ci-control-bridge
ddc-ci-bridge
`Or using npx:
bash
npx ddc-ci-control-bridge
`3. The server will display:
🔌 MCP Server: http://192.168.1.100:8000
Transport: sse
API Key: your-api...
Note the IP address and port for client configuration.
Step 2: Configure MCP Clients (Remote Connection)
Cursor:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"url": "http://192.168.1.100:8000",
"headers": {
"Authorization": "Bearer your-secure-random-api-key-here"
}
}
}
}
`VS Code:
json
"mcp": {
"servers": {
"ddc-ci-bridge": {
"type": "http",
"url": "http://192.168.1.100:8000",
"headers": {
"Authorization": "Bearer your-secure-random-api-key-here"
}
}
}
}
`Claude Desktop:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"url": "http://192.168.1.100:8000",
"headers": {
"Authorization": "Bearer your-secure-random-api-key-here"
}
}
}
}
`Windsurf:
json
{
"mcpServers": {
"ddc-ci-bridge": {
"serverUrl": "http://192.168.1.100:8000",
"headers": {
"Authorization": "Bearer your-secure-random-api-key-here"
}
}
}
}
`Note: Replace
with the actual IP address of your monitor-connected machine, and use the same API key you configured in the server's .env file.---
$3
1. Create a
.env file:
`bash
cp .env.example .env
`2. Edit
and configure:
`bash
DDC_API_KEY=your-secret-api-key-hereEnable MQTT for automation platforms (optional)
MQTT_ENABLED=false
MQTT_HOST=localhost
MQTT_PORT=1883
`To enable MQTT: Set
and change MQTT_HOST to your MQTT broker IP (e.g., Home Assistant IP).3. Start the server:
`bash
npm run dev
`MQTT Integration
This server acts as an MQTT client and can connect to any MQTT broker.
$3
- Home Assistant: Auto-discovery via MQTT Discovery Protocol → See Home Assistant Guide
- openHAB: MQTT binding with manual thing configuration
- Node-RED: Subscribe to topics for custom flows
- Domoticz: MQTT integration
- Generic MQTT: Any platform that supports MQTT pub/sub
$3
ddc-monitor/{index}/brightness/set|get
ddc-monitor/{index}/contrast/set|get
ddc-monitor/{index}/vcp/{code}/set|get
ddc-monitor/{index}/power/set
ddc-monitor/{index}/state
ddc-monitor/bridge/status
MCP Resources
-
- List all available monitors
- monitor://{index}/capabilities - Full VCP code scan results
- monitor://{index}/current-values - Current values of all supported codes
- monitor://{index}/info - Monitor metadataMCP Tools
-
get_vcp_code - Read a specific VCP code value
- set_vcp_code - Write a value to a VCP code
- get_brightness - Get monitor brightness (0-100)
- set_brightness - Set monitor brightness (0-100)
- refresh_monitors - Re-scan monitors and VCP capabilitiesDevelopment
$3
`bash
npm run build
`$3
bash
npm run build:executables
`This creates standalone executables in
for Windows, Linux, and macOS.$3
`bash
npm run dev
`Requirements
- DDC/CI Support: Your monitor must support DDC/CI (most modern monitors do)
- DDC/CI Enabled: Enable DDC/CI in your monitor's OSD settings
- Permissions: On Linux, you may need to add your user to the
group$3
`bash
sudo usermod -a -G i2c $USER
sudo modprobe i2c-dev
`Log out and log back in for group changes to take effect.
Environment Variables
See
for all available configuration options.Key variables:
-
DDC_API_KEY - API key for server authentication (required)
- MCP_TRANSPORT - Transport type: sse or stdio (default: sse)
- MCP_PORT - HTTP port for SSE transport (default: 8000)
- MQTT_ENABLED - Enable MQTT client (default: false)
- MQTT_HOST - MQTT broker IP/hostname (default: localhost)
- MQTT_PORT - MQTT broker port (default: 1883)
- MQTT_USERNAME - Auto-configured as ddc-mcp
- - Auto-configured from DDC_API_KEYArchitecture
┌─────────────────────────────────────────┐
│ DDC/CI Control Bridge │
│ │
│ ┌─────────────────┐ ┌──────────────┐ │
│ │ MCP Server │ │ MQTT Client │ │
│ │ - Resources │ │ - Pub/Sub │ │
│ │ - Tools │ │ - Discovery │ │
│ └────────┬────────┘ └──────┬───────┘ │
│ │ │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ DDC Controller │ │
│ │ - VCP Scanning │ │
│ │ - Read/Write │ │
│ └────────┬────────┘ │
└────────────────────┼───────────────────┘
│
┌────────▼────────┐
│ Physical Monitor│
│ (DDC/CI) │
└─────────────────┘External Clients:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ AI Agents │ │ MQTT Broker │ │ Automation │
│ (via MCP) │ │ (any broker) │ │ Platforms │
└──────────────┘ └──────────────┘ └──────────────┘
License
MIT
Documentation
- Home Assistant Integration Guide - Complete HA setup
- Development Guide - Technical architecture and development details
Contributing
Contributions welcome! Please open an issue or PR.
Troubleshooting
$3
- Ensure DDC/CI is enabled in your monitor's OSD settings
- On Linux, check if i2c devices are available:
- Try running with elevated permissions (not recommended for production)
$3
- Verify MQTT broker is running
- Check credentials match the server output
- Ensure firewall allows MQTT port (1883)
$3
- Check server logs for errors
- Verify monitor supports the VCP code
- Some codes may be read-only
- Try restarting both server and Home Assistant