Monitor Control MCP

基于 MCP (Model Context Protocol) 的屏幕亮度控制工具，让 AI 助手可以智能调节你的显示器亮度。

本项目全程使用Qwen Code CLI程序Qwen3.5-Plus模型生成

✨ 功能特性

• 🔍 显示器检测: 获取所有支持 DDC/CI 协议的显示器信息
• 🎯 精确控制: 设置显示器亮度为指定百分比 (0-100%)
• 📈 相对调节: 在当前亮度基础上增加或减少亮度
• 🖥️ 多显示器支持: 可同时控制所有显示器或指定特定显示器
• 🛡️ 资源管理: 自动管理显示器句柄，防止资源泄漏
• 🎨 对比度控制: 设置和查询显示器对比度 (0-100%)
• 🌈 RGB 增益查询: 查询显示器的红/绿/蓝增益信息（设置功能因硬件兼容性问题已禁用）

📋 系统要求

• 操作系统: Windows 10/11
• Python: 3.10 或更高版本
• 显示器: 支持 DDC/CI 协议的显示器
• 权限: 可能需要管理员权限

🚀 快速开始

1. 安装

方式 A: 使用 uv（推荐）

# 克隆仓库
git clone https://github.com/your-username/monitor-control-mcp.git
cd monitor-control-mcp

# 安装依赖
uv sync

方式 B: 使用 pip

# 克隆仓库
git clone https://github.com/your-username/monitor-control-mcp.git
cd monitor-control-mcp

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate  # Windows

# 安装依赖
pip install -e .

2. 测试安装

# 直接运行测试
uv run python monitor_brightness.py

# 或使用 pip 安装后
python monitor_brightness.py

🔧 MCP 客户端配置

Claude Desktop 配置

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "monitor-control": {
      "command": "uv",
      "args": ["run", "monitor-control-mcp"],
      "cwd": "C:\\path\\to\\monitor-control-mcp"
    }
  }
}

macOS (~/Library/Application Support/Claude/claude_desktop_config.json):

⚠️ 注意：此工具仅支持 Windows 系统。macOS 用户需要使用其他方法。

Cursor IDE 配置

在 Cursor 的设置中，找到 MCP 配置，添加：

{
  "mcpServers": {
    "monitor-control": {
      "command": "uv",
      "args": ["run", "monitor-control-mcp"],
      "cwd": "C:\\path\\to\\monitor-control-mcp"
    }
  }
}

其他 MCP 客户端

使用以下通用配置：

• command: uv (或 Python 可执行文件路径)
• args: ["run", "monitor-control-mcp"]
• cwd: 项目的绝对路径

🛠️ 可用工具

1. get_monitor_info - 获取显示器信息

获取所有显示器的详细信息和当前亮度。

参数: 无

返回示例:

{
  "success": true,
  "monitor_count": 2,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "current_brightness": 60,
      "min_brightness": 0,
      "max_brightness": 100,
      "raw_current": 60
    },
    {
      "description": "LG UltraFine",
      "current_brightness": 45,
      "min_brightness": 0,
      "max_brightness": 100,
      "raw_current": 45
    }
  ]
}

2. set_brightness - 设置亮度

将显示器亮度设置为指定百分比。

参数:

参数名	类型	必填	描述
brightness	integer	✅	目标亮度百分比 (0-100)
monitor_description	string	❌	显示器描述关键字，用于指定特定显示器

示例:

// 将所有显示器设置为 50% 亮度
{"brightness": 50}

// 仅设置 Dell 显示器
{"brightness": 70, "monitor_description": "Dell"}

3. adjust_brightness - 相对调节亮度

在当前亮度基础上增加或减少亮度。

参数:

参数名	类型	必填	描述
delta	integer	✅	亮度调整幅度 (-100 到 100)
monitor_description	string	❌	显示器描述关键字

示例:

// 增加 10% 亮度
{"delta": 10}

// 降低 20% 亮度
{"delta": -20}

// 仅调节特定显示器
{"delta": 5, "monitor_description": "LG"}

4. set_contrast - 设置对比度

将显示器对比度设置为指定百分比。

参数:

参数名	类型	必填	描述
contrast	integer	✅	目标对比度百分比 (0-100)
monitor_description	string	❌	显示器描述关键字，用于指定特定显示器

示例:

// 将所有显示器对比度设置为 70%
{"contrast": 70}

// 仅设置 Dell 显示器
{"contrast": 80, "monitor_description": "Dell"}

5. get_contrast - 获取对比度信息

获取显示器的当前对比度信息。

参数:

参数名	类型	必填	描述
monitor_description	string	❌	显示器描述关键字，用于指定特定显示器

返回示例:

{
  "success": true,
  "monitor_count": 1,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "success": true,
      "current": 70,
      "min": 0,
      "max": 100,
      "percent": 70
    }
  ]
}

6. get_gain - 获取指定颜色增益

获取显示器指定颜色通道的增益信息。

参数:

参数名	类型	必填	描述
color	string	✅	颜色通道：red、green 或 blue
monitor_description	string	❌	显示器描述关键字

返回示例:

{
  "success": true,
  "monitor_count": 1,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "success": true,
      "current": 50,
      "min": 1,
      "max": 100,
      "percent": 49
    }
  ]
}

7. get_all_gains - 获取所有颜色增益

一次性获取显示器所有 RGB 增益信息。

参数:

参数名	类型	必填	描述
monitor_description	string	❌	显示器描述关键字

返回示例:

{
  "success": true,
  "monitor_count": 1,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "success": true,
      "gains": {
        "red": {
          "current": 50,
          "min": 1,
          "max": 100,
          "percent": 49
        },
        "green": {
          "current": 50,
          "min": 1,
          "max": 100,
          "percent": 49
        },
        "blue": {
          "current": 50,
          "min": 1,
          "max": 100,
          "percent": 49
        }
      }
    }
  ]
}

⚠️ 关于 RGB 增益设置的说明

set_gain 工具已暂时禁用，原因如下：

• 硬件兼容性差: 许多显示器不支持通过 DDC/CI 写入 RGB 增益值
• 只读限制: 部分显示器允许读取增益值但不允许修改
• 预设模式限制: 显示器处于预设模式（如标准、游戏、电影等）时通常禁止修改

如果未来需要启用此功能，请确保：

1. 显示器处于用户自定义模式
2. 在显示器 OSD 菜单中启用 DDC/CI 写入权限
3. 不同显示器型号可能需要不同的处理方式

💡 使用示例

场景 1: 查询当前所有显示器状态

用户：我现在的显示器亮度是多少？

AI: 让我帮你查询一下。 [使用 get_monitor_info 工具] 你目前有 2 台显示器：

• Dell U2720Q: 亮度 60%
• LG UltraFine: 亮度 45%

场景 2: 设置夜间模式

用户：太亮了，调暗一点

AI: 好的，我来帮你降低亮度。 [使用 adjust_brightness 工具，delta: -20] 已将亮度降低 20%，现在更舒适了。

场景 3: 精确控制

用户：把亮度设为 50%

AI: 没问题。 [使用 set_brightness 工具，brightness: 50] 已将所有显示器亮度设置为 50%。

场景 4: 控制特定显示器

用户：只调暗主显示器

AI: 好的。 [使用 set_brightness 工具，brightness: 30, monitor_description: "Dell"] 已将 Dell 显示器亮度设置为 30%。

场景 5: 调整对比度

用户：把对比度调高一些

AI: 好的，我来帮你调整对比度。 [先使用 get_contrast 查询当前值，再使用 set_contrast 设置为 75%] 已将对比度从 60% 调整为 75%。

场景 6: 查询色彩平衡

用户：我的显示器 RGB 增益设置怎么样？

AI: 让我帮你检查一下。 [使用 get_all_gains 工具] 你的显示器 RGB 增益设置如下：

• 红色：50%
• 绿色：50%
• 蓝色：50% 色彩平衡正常。

🔍 故障排除

问题 1: "未检测到任何支持 DDC/CI 的物理显示器"

可能原因:

1. 显示器不支持 DDC/CI 协议
2. DDC/CI 功能在显示器 OSD 菜单中被禁用
3. 使用了不支持的转接头或线缆

解决方案:

1. 检查显示器规格，确认支持 DDC/CI
2. 在显示器 OSD 菜单中找到并启用 "DDC/CI" 选项
3. 使用原装或高质量的 DisplayPort/HDMI 线缆
4. 避免使用廉价的转接头

问题 2: "获取亮度信息失败" 或 "设置亮度失败"

可能原因:

• 权限不足
• 显示器暂时无法响应

解决方案:

1. 以管理员身份运行终端/IDE
2. 重启显示器后重试
3. 检查是否有其他软件正在控制显示器亮度

问题 3: 笔记本内置屏幕无法调节

说明: 某些笔记本的内置屏幕不支持 DDC/CI 协议，这是正常现象。此工具主要适用于外接显示器。

替代方案: 使用 Windows 内置的亮度调节功能或笔记本厂商提供的控制软件。

问题 4: MCP 服务器无法启动

检查步骤:

1. 确认 Python 版本 >= 3.10
2. 确认已安装所有依赖：uv sync
3. 检查配置文件中的路径是否正确
4. 查看错误日志

📁 项目结构

monitor-control-mcp/
├── mcp_server.py          # MCP 服务器主程序
├── monitor_brightness.py  # 显示器亮度控制模块
├── pyproject.toml         # 项目配置和依赖
├── README.md              # 项目文档
├── LICENSE                # 开源许可证
├── .gitignore             # Git 忽略文件
└── tests/                 # 测试目录（待添加）
    └── test_server.py

🔧 开发指南

本地开发

# 克隆仓库
git clone https://github.com/your-username/monitor-control-mcp.git
cd monitor-control-mcp

# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest

直接测试模块

# 测试亮度控制模块
uv run python monitor_brightness.py

# 测试 MCP 服务器（需要 MCP 客户端连接）
uv run python mcp_server.py

构建分发包

# 使用 uv 构建
uv build

# 或使用 pip
pip install build
python -m build

📝 API 参考

MonitorController 类

底层控制器类，管理显示器句柄和 DDC/CI 通信。

from monitor_brightness import MonitorController

controller = MonitorController()
controller.load_dll()

# 获取显示器列表
monitors = controller.get_monitor_handles()

# 设置亮度
success, message = controller.set_brightness_for_monitor(handle, 50)

# 获取当前亮度
current, min_val, max_val = controller.get_current_brightness(handle)

# 清理资源
controller.cleanup_monitors(monitors)

便捷函数

模块提供的便捷函数：

from monitor_brightness import (
    control_monitor_brightness,  # 控制亮度（高级 API）
    get_monitor_handles,         # 获取显示器句柄
    get_current_brightness,      # 获取当前亮度
    set_brightness_for_monitor,  # 设置单个显示器亮度
    cleanup_monitors,            # 清理资源
)

# 使用高级 API
result = control_monitor_brightness(50)  # 设置所有显示器为 50%
result = control_monitor_brightness(50, "Dell")  # 仅设置 Dell 显示器

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• MCP 协议文档
• DDC/CI 规范
• Python 官方网站

⭐ 致谢

感谢使用本项目！如果这个项目对你有帮助，请给一个 Star ⭐

---

注意: 本项目仅适用于 Windows 系统，需要显示器支持 DDC/CI 协议。