DDC/CI Control Bridge

Official

by Defozo · TypeScript

Control monitor brightness, contrast, power and input via DDC/CI with MCP and MQTT support.

Control monitor brightness, contrast, power and input via DDC/CI protocol.

Topics

ddc-cidisplaydisplayporthdmihomeassistanthomeautomationmcpmcp-servermonitormqttmqtt-clientusb-c

README.md20 KBView on GitHub

DDC/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

Installation

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-win.exe
Linux: ddc-ci-bridge-linux
macOS: ddc-ci-bridge-macos

⚠️ Note: The executable requires DDC_API_KEY environment variable to be set, or it will exit immediately.

Windows:

cmd

# Set API key (required)
set DDC_API_KEY=your-secret-key

# Run the executable
ddc-ci-bridge-win.exe

# Or set multiple environment variables
set DDC_API_KEY=your-secret-key
set MQTT_ENABLED=true
set MQTT_HOST=192.168.1.100
ddc-ci-bridge-win.exe

Linux/macOS:

bash

# Make executable (first time only)
chmod +x ddc-ci-bridge-linux  # or ddc-ci-bridge-macos

# Run with API key (required)
DDC_API_KEY=your-secret-key ./ddc-ci-bridge-linux

# Or with multiple 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": "C:\\path\\to\\ddc-ci-bridge-win.exe",
      "args": [],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

MCP Client Setup

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.

<details> <summary>Install in Cursor (Local)</summary>

Go to: Settings → Cursor Settings → MCP → Add new global MCP server

Or paste the following configuration into your ~/.cursor/mcp.json 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 MQTT_ENABLED=true and configure MQTT_HOST to your MQTT broker IP for automation platform integration.

</details> <details> <summary>Install in VS Code (Local)</summary>

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"
      }
    }
  }
}

</details> <details> <summary>Install in Claude Desktop (Local)</summary>

Open Claude Desktop developer settings and edit your claude_desktop_config.json file:

json

{
  "mcpServers": {
    "ddc-ci-bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

</details> <details> <summary>Install in Claude Code (Local)</summary>

Run this command:

claude mcp add ddc-ci-bridge -- npx -y ddc-ci-control-bridge

</details> <details> <summary>Install in Windsurf (Local)</summary>

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"
      }
    }
  }
}

</details> <details> <summary>Install in Cline (Local)</summary>

Add this to your Cline MCP configuration:

json

{
  "mcpServers": {
    "ddc-ci-bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

</details> <details> <summary>Install in Zed (Local)</summary>

Add this to your Zed settings.json:

json

{
  "context_servers": {
    "DDC/CI Bridge": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

</details> <details> <summary>Install in Roo Code (Local)</summary>

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"
      }
    }
  }
}

</details> <details> <summary>Install in Augment Code (Local)</summary>

Option A: Using the UI

Click the hamburger menu
Select Settings
Navigate to Tools section
Click + Add MCP button
Enter command: npx -y ddc-ci-control-bridge
Name: DDC/CI Bridge
Click Add

Option B: Manual Configuration

Add to settings.json:

json

"augment.advanced": {
  "mcpServers": [
    {
      "name": "ddc-ci-bridge",
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  ]
}

</details> <details> <summary>Install in JetBrains AI Assistant (Local)</summary>

Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP)
Click + Add
Select As JSON from the dropdown
Add this configuration:

json

{
  "mcpServers": {
    "ddc-ci-bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

Click Apply to save changes

</details> <details> <summary>Install in Warp (Local)</summary>

Navigate Settings → AI → Manage MCP servers
Click + Add button
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
  }
}

Click Save

</details> <details> <summary>Install in OpenAI Codex (Local)</summary>

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"

</details> <details> <summary>Install in LM Studio (Local)</summary>

Navigate to Program (right side) → Install → Edit mcp.json
Add this configuration:

json

{
  "mcpServers": {
    "DDC/CI Bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

Click Save
Toggle the MCP server on/off from the right side panel

</details> <details> <summary>Install in Qodo Gen (Local)</summary>

Open Qodo Gen chat panel in VSCode or IntelliJ
Click Connect more tools
Click + Add new MCP
Add this configuration:

json

{
  "mcpServers": {
    "ddc-ci-bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

</details> <details> <summary>Install in Perplexity Desktop (Local)</summary>

Navigate Perplexity → Settings
Select Connectors
Click Add Connector
Select Advanced
Enter Server Name: DDC/CI Bridge
Paste this JSON:

json

{
  "command": "npx",
  "args": ["-y", "ddc-ci-control-bridge"],
  "env": {
    "FASTMCP_API_KEY": "your-api-key-here",
    "MQTT_ENABLED": "false"
  }
}

Click Save

</details> <details> <summary>Install in Kiro (Local)</summary>

Navigate Kiro → MCP Servers
Click + Add button
Paste this configuration:

json

{
  "mcpServers": {
    "DDC/CI Bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Click Save

</details> <details> <summary>Install in BoltAI (Local)</summary>

Open Settings → Plugins
Enter this JSON:

json

{
  "mcpServers": {
    "ddc-ci-bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

Save and restart if needed

</details> <details> <summary>Install in Zencoder (Local)</summary>

Go to Zencoder menu (...)
Select Agent tools
Click Add custom MCP
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"
  }
}

Click Install

</details> <details> <summary>Install in Amazon Q Developer CLI (Local)</summary>

Add to your Amazon Q configuration:

json

{
  "mcpServers": {
    "ddc-ci-bridge": {
      "command": "npx",
      "args": ["-y", "ddc-ci-control-bridge"],
      "env": {
        "MQTT_ENABLED": "false"
      }
    }
  }
}

</details> <details> <summary>Using Bun or Deno</summary>

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"
      }
    }
  }
}

</details> <details> <summary>Windows-Specific Configuration</summary>

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": []
    }
  }
}

</details>

🌐 Remote Setup (HTTP - Different Machines)

Use this if you want to access monitor controls from a different machine on your network.

<details> <summary>Step 1: Set up the MCP Server on Monitor-Connected Machine</summary>

On the machine with monitors, create a .env file:

bash

DDC_API_KEY=your-secure-random-api-key-here
MCP_TRANSPORT=sse
MCP_PORT=8000

# Optional: Enable MQTT for automation platforms
MQTT_ENABLED=false
MQTT_HOST=localhost
MQTT_PORT=1883

Start the server:

bash

npm install -g ddc-ci-control-bridge
ddc-ci-bridge

Or using npx:

bash

npx ddc-ci-control-bridge

The server will display:

code

🔌 MCP Server: http://192.168.1.100:8000
   Transport: sse
   API Key: your-api...

Note the IP address and port for client configuration.

</details> <details> <summary>Step 2: Configure MCP Clients (Remote Connection)</summary>

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 192.168.1.100 with the actual IP address of your monitor-connected machine, and use the same API key you configured in the server's .env file.

</details>

Configuration

Create a .env file:

bash

cp .env.example .env

Edit .env and configure:

bash

DDC_API_KEY=your-secret-api-key-here

# Enable MQTT for automation platforms (optional)
MQTT_ENABLED=false
MQTT_HOST=localhost
MQTT_PORT=1883

To enable MQTT: Set MQTT_ENABLED=true and change MQTT_HOST to your MQTT broker IP (e.g., Home Assistant IP).

Start the server:

bash

npm run dev

MQTT Integration

This server acts as an MQTT client and can connect to any MQTT broker.

Supported Platforms

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

MQTT Topics

code

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

monitor://list - 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 metadata

MCP 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 capabilities

Development

Build

bash

npm run build

Build Executables

bash

npm run build:executables

This creates standalone executables in dist/bin/ for Windows, Linux, and macOS.

Run in Development

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 i2c group

Linux Setup

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 .env.example 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
MQTT_PASSWORD - Auto-configured from DDC_API_KEY

Architecture

code

┌─────────────────────────────────────────┐
│       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

No monitors found

Ensure DDC/CI is enabled in your monitor's OSD settings
On Linux, check if i2c devices are available: ls -l /dev/i2c-*
Try running with elevated permissions (not recommended for production)

MQTT connection failed

Verify MQTT broker is running
Check credentials match the server output
Ensure firewall allows MQTT port (1883)

Commands not working

Check server logs for errors
Verify monitor supports the VCP code
Some codes may be read-only
Try restarting both server and Home Assistant

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ddc-ci-control-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "ddc-ci-control-bridge@1.0.5"
      ]
    }
  }
}

GitHub

Stars: 5
Forks: 0
Open issues: 1
Language: TypeScript
License: MIT License
Default branch: main
Latest release: v1.0.5 · 10/15/2025
Created: 10/15/2025
Updated: 6/3/2026

Trust grades

License: A
Maintenance: C
Quality: Not tested yet

Graded A-F from license permissiveness and commit recency; a cross-model quality score is coming soon.

npm

Package: ddc-ci-control-bridge
Latest version: 1.0.5
Published: 10/15/2025

Details

Name: io.github.Defozo/ddc-ci-control-bridge
Version: 1.0.5
Status: active
Published: 10/15/2025
Updated: 10/15/2025
Official: Yes
Repository: Defozo/ddc-ci-control-bridge
Registry record: View server.json

Connect agentage Memory

The cross-vendor memory every AI reads and writes - Claude, Cursor, ChatGPT - mirrored as plain markdown files you own and can export anytime.

MCP endpointmemory.agentage.io/mcp

Connect Memory

One memory. Every AI. Owned by you.