qinglong-mcp

Model Context Protocol (MCP) server for Qinglong panel（青龙面板） — 基于官方 Open API（/open/*），让任何支持 MCP 的 AI 客户端用自然语言管理青龙：定时任务、环境变量、脚本、订阅、通知、日志、配置与依赖。

兼容 WorkBuddy / Claude Desktop / Codex / OpenCode / Cline / 自研 agent，协议合规即用，不绑定任何客户端。

目录

• 功能特性
• 安装
• 快速开始
• 环境变量
• 工具清单
• 传输模式
• 开发与测试
• 安全提示
• License

功能特性

• 通用：MCP 协议标准实现，任何客户端直接接入
• 轻量：纯 API 客户端，无数据库、无常驻进程，青龙服务器零额外负担
• 双传输：默认 stdio（本地即用），可选 Streamable HTTP（多 agent 远程共享）
• 42 个工具：覆盖 crons / envs / scripts / subscriptions / system / logs / configs / dependencies 全模块
• 自动认证：token 获取、缓存、过期刷新、401 自动重试，开箱即用

安装

方式一：AI 自动安装（推荐）

把下面这段直接发给你的 AI 客户端（WorkBuddy / Claude / Codex / OpenCode 等），AI 会自动完成安装与注册，全程无需你手动指定任何路径：

请帮我自动安装并接入 qinglong-mcp：
仓库：https://github.com/YSJohnson/qinglong-mcp.git

1. 自动选择一个合适的本地路径，克隆该仓库
2. 进入项目目录执行 npm install && npm run build，确认 dist/index.js 生成成功
3. 自动识别当前运行环境，把 MCP server 注册到对应客户端配置：
4. 注册需要三个环境变量，若我未提供请向我询问：QL_BASE_URL（青龙面板地址）、QL_CLIENT_ID、QL_CLIENT_SECRET
5. 完成后用「列出青龙的定时任务」验证连通，并报告安装路径与配置位置

方式二：本地源码运行（手动）

git clone https://github.com/YSJohnson/qinglong-mcp.git
cd qinglong-mcp
npm install
npm run build

编译产物在 dist/ 目录，将客户端配置指向 dist/index.js 即可（见下）。

快速开始

1. 准备青龙凭证

青龙面板 → 系统设置 → 应用设置 → 添加应用，获取 client_id 与 client_secret。

2. 客户端配置（stdio）

四份现成示例见 examples/：WorkBuddy / Claude Desktop / Codex / OpenCode。

WorkBuddy / Claude Desktop —— 在 MCP 配置的 mcpServers 中加入：

{
  "mcpServers": {
    "qinglong": {
      "command": "node",
      "args": ["/你的路径/qinglong-mcp/dist/index.js"],
      "env": {
        "QL_BASE_URL": "http://你的服务器IP:5700",
        "QL_CLIENT_ID": "你的client_id",
        "QL_CLIENT_SECRET": "你的client_secret"
      }
    }
  }
}

Codex CLI：

codex mcp add qinglong \
  --env QL_BASE_URL=http://你的服务器IP:5700 \
  --env QL_CLIENT_ID=你的client_id \
  --env QL_CLIENT_SECRET=你的client_secret \
  -- node /你的路径/qinglong-mcp/dist/index.js

OpenCode —— 在 ~/.config/opencode/opencode.json 中：

{
  "mcp": {
    "qinglong": {
      "type": "local",
      "command": ["node", "/你的路径/qinglong-mcp/dist/index.js"],
      "environment": {
        "QL_BASE_URL": "http://你的服务器IP:5700",
        "QL_CLIENT_ID": "你的client_id",
        "QL_CLIENT_SECRET": "你的client_secret"
      }
    }
  }
}

3. 使用示例

配置完成后，直接对 agent 说：

• 「列出青龙面板的所有定时任务」
• 「把 xxx 任务改成每天 8 点运行」
• 「给 JD_COOKIE 添加环境变量」
• 「看 xxx 任务上次运行的日志」

环境变量

变量	必填	说明
QL_BASE_URL	✅	青龙面板地址，如 http://192.168.1.100:5700
QL_CLIENT_ID	✅*	应用 client_id（与 QL_TOKEN 二选一）
QL_CLIENT_SECRET	✅*	应用 client_secret
QL_TOKEN	-	直接提供已签发 token，跳过 client_id/secret
QL_TIMEOUT_MS	-	请求超时毫秒数，默认 30000

工具清单

模块	工具
Crons 定时任务	list_crons create_cron update_cron delete_crons run_crons stop_crons enable_crons disable_crons get_cron_log add_cron_labels remove_cron_labels
Envs 环境变量	list_envs get_env create_env update_env delete_envs enable_envs disable_envs
Scripts 脚本	list_scripts get_script run_script save_script delete_script
Subscriptions 订阅	list_subscriptions create_subscription run_subscriptions stop_subscriptions enable_subscriptions disable_subscriptions get_subscription_log
System 系统	get_system_info send_notification run_command* stop_command
Logs 日志	list_logs get_log
Configs 配置	list_configs get_config save_config
Dependencies 依赖	list_dependencies create_dependencies delete_dependencies

* run_command 会在青龙服务器上执行任意 shell 命令，属高危操作，请谨慎使用。

传输模式

stdio（默认，推荐）

由客户端按需拉起进程，全客户端兼容，无端口、无常驻。

Streamable HTTP（多 agent 远程共享）

QL_BASE_URL=http://127.0.0.1:5700 QL_CLIENT_ID=xxx QL_CLIENT_SECRET=xxx \
  node /你的路径/qinglong-mcp/dist/index.js --transport http --port 3000

客户端侧改用 URL 连接：

{ "mcpServers": { "qinglong": { "url": "http://主机IP:3000/mcp" } } }

⚠️ HTTP 模式暴露的是「远程执行能力」，请勿裸暴露公网，务必加反向代理鉴权。

开发与测试

npm install
npm run build                    # tsc 编译到 dist/
node scripts/mock-server.mjs     # 启动本地 mock 青龙（端口 18700）
node scripts/smoke-test.mjs      # stdio 端到端冒烟测试（需 mock 已启动）

安全提示

• delete_*、save_config、save_script、run_command 为高风险操作，工具描述已标注警告，调用前请确认。
• 凭证只放在客户端本地配置（如 ~/.codex/config.toml、mcp.json），切勿提交到仓库。
• 若配合 Codex 等工具设置 approval_policy = "never"（免确认），强烈建议在青龙「应用设置」中收窄应用模块权限。

License

MIT © 2026 YSJohnson