Monitor Control Mcp
Overview
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 增益值
- 只读限制: 部分显示器允许读取增益值但不允许修改
- 预设模式限制: 显示器处于预设模式（如标准、游戏、电影等）时通常禁止修改
如果未来需要启用此功能，请确保：
- 显示器处于用户自定义模式
- 在显示器 OSD 菜单中启用 DDC/CI 写入权限
- 不同显示器型号可能需要不同的处理方式
💡 使用示例
场景 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 的物理显示器"
可能原因:
- 显示器不支持 DDC/CI 协议
- DDC/CI 功能在显示器 OSD 菜单中被禁用
- 使用了不支持的转接头或线缆
解决方案:
- 检查显示器规格，确认支持 DDC/CI
- 在显示器 OSD 菜单中找到并启用 "DDC/CI" 选项
- 使用原装或高质量的 DisplayPort/HDMI 线缆
- 避免使用廉价的转接头
问题 2: "获取亮度信息失败" 或 "设置亮度失败"
可能原因:
- 权限不足
- 显示器暂时无法响应
解决方案:
- 以管理员身份运行终端/IDE
- 重启显示器后重试
- 检查是否有其他软件正在控制显示器亮度
问题 3: 笔记本内置屏幕无法调节
说明: 某些笔记本的内置屏幕不支持 DDC/CI 协议，这是正常现象。此工具主要适用于外接显示器。
替代方案: 使用 Windows 内置的亮度调节功能或笔记本厂商提供的控制软件。
问题 4: MCP 服务器无法启动
检查步骤:
- 确认 Python 版本 >= 3.10
- 确认已安装所有依赖：
uv sync - 检查配置文件中的路径是否正确
- 查看错误日志
📁 项目结构
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 显示器
🤝 贡献
欢迎贡献代码、报告问题或提出建议！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🔗 相关链接
⭐ 致谢
感谢使用本项目！如果这个项目对你有帮助，请给一个 Star ⭐
注意: 本项目仅适用于 Windows 系统，需要显示器支持 DDC/CI 协议。
Server Config
{
"mcpServers": {
"monitor-control": {
"command": "uv",
"args": [
"run",
"monitor-control-mcp"
],
"cwd": "C:\\path\\to\\monitor-control-mcp"
}
}
}Project Info
Created At
3 months agoUpdated At
3 months agoAuthor Name
mingdediStar
-Language
-License
-Recommend Servers
View AllTavily Mcp
@tavily-ai
JavaScript
a year ago
Playwright Mcp
@microsoft
Playwright MCP server
TypeScript
10 months ago