How do I use qinglong-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qinglong-mcp 列出青龙面板的所有定时任务" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

qinglong-mcp

by YSJohnson

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

qinglong-mcp

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

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

功能特性

通用：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

Available Tools

42 tools

add_cron_labelsB

Add labels to cron tasks.

Inputs: ids (required), labels (required).

create_cronA

Create a new cron task. Required: command (e.g. ql task xxx.js or any shell command) and schedule (cron expression, e.g. 0 8 * * *).

Inputs: command (required), schedule (required), name, labels, +3 more.

create_dependenciesA

Install dependencies. type: 1 = node, 2 = python, 3 = linux. Accepts a single dependency or an array (envs / items).

Inputs: name, type, items, remark.

create_envA

Create an environment variable. Name must start with a letter/underscore, only letters, digits and underscores allowed.

Inputs: name (required), value (required), remarks.

create_subscriptionA

Create a repository subscription. Required: url (git/http repo URL). type defaults to public-repo, schedule_type defaults to cron.

Inputs: url (required), name, type, alias, +7 more.

delete_cronsA

Delete cron tasks by ids. ⚠️ Irreversible.

Inputs: ids (required).

delete_dependenciesA

Delete installed dependencies by ids. ⚠️ Irreversible.

Inputs: ids (required).

delete_envsA

Delete environment variables by ids. ⚠️ Irreversible.

Inputs: ids (required).

delete_scriptA

Delete a script file. ⚠️ Irreversible.

Inputs: filename (required), path.

disable_cronsA

Disable cron tasks by ids (pause scheduling).

Inputs: ids (required).

disable_envsB

Disable environment variables by ids.

Inputs: ids (required).

disable_subscriptionsB

Disable subscriptions by ids.

Inputs: ids (required).

enable_cronsA

Enable cron tasks by ids (resume scheduling).

Inputs: ids (required).

enable_envsC

Enable environment variables by ids.

Inputs: ids (required).

enable_subscriptionsC

Enable subscriptions by ids.

Inputs: ids (required).

get_configA

Read a config file's content by path.

Inputs: path (required).

get_cron_logA

Get the latest execution log of a cron task by id.

Inputs: id (required).

get_envA

Get a single environment variable by id.

Inputs: id (required).

get_logA

Read a log file's content by path/file.

Inputs: file, path.

get_scriptC

Read a script file's content.

Inputs: file (required), path.

get_subscription_logB

Get the latest log of a subscription by id.

Inputs: id (required).

get_system_infoA

Get Qinglong system info: version, init state, branch, changelog.

Inputs: no named parameters.

list_configsA

List Qinglong config files (config.sh, auth.json etc.).

Inputs: no named parameters.

list_cronsA

List cron tasks in Qinglong panel. Returns every task with id, name, command, schedule, status etc. Optionally filter with searchValue.

Inputs: searchValue.

list_dependenciesA

List installed dependencies (node/python/linux packages).

Inputs: no named parameters.

list_envsA

List environment variables (cookies, credentials etc.) in Qinglong. Optionally filter with searchValue.

Inputs: searchValue.

list_logsA

List accessible log files on the Qinglong server.

Inputs: no named parameters.

list_scriptsB

List script files in Qinglong's script directory.

Inputs: path.

list_subscriptionsB

List repository subscriptions in Qinglong.

Inputs: searchValue.

remove_cron_labelsB

Remove labels from cron tasks.

Inputs: ids (required), labels (required).

run_commandA

⚠️ DANGEROUS: execute an arbitrary shell command on the Qinglong server (host shell, not container-shell restricted). Only for advanced use; prefer dedicated tools (run_crons / run_script) when possible.

Inputs: command (required).

run_cronsA

Trigger cron tasks to run immediately (async; use get_cron_log to inspect output).

Inputs: ids (required).

run_scriptA

Run a script file directly (ad-hoc execution, not via cron).

Inputs: filename (required), path, content.

run_subscriptionsC

Pull/run repository subscriptions by ids.

Inputs: ids (required).

save_configA

Save (create/overwrite) a config file. ⚠️ Can change panel behavior.

Inputs: name (required), content (required).

save_scriptA

Create or overwrite a script file with the given content.

Inputs: content (required), filename (required), path.

send_notificationA

Send a notification through Qinglong's notification system (Server酱/PushPlus/Bark/Telegram/钉钉/企业微信/邮件 etc.). Provide notificationInfo with a "type" matching the configured channel and its keys, e.g. {"type":"serverChan","serverChanKey":"SCxxx"}; omit to use system default channel.

Inputs: title (required), content (required), notificationInfo.

stop_commandA

Stop a running command on the Qinglong server by pid (or command text).

Inputs: pid, command.

stop_cronsB

Stop running cron tasks by ids.

Inputs: ids (required).

stop_subscriptionsB

Stop running subscriptions by ids.

Inputs: ids (required).

update_cronA

Update an existing cron task by id. Only include the fields you want to change; id is required.

Inputs: id (required), name, labels, command, +3 more.

update_envA

Update an environment variable (name/value/remarks) by id.

Inputs: id (required), name, value, remarks.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-08-08 18:35 across 42 tools

Disambiguation5/5

Each tool targets a distinct resource and action. Although run_crons, run_script, and run_command all involve execution, their descriptions clearly differentiate between cron tasks, script files, and arbitrary shell commands. Similarly, the various log tools are specific to their source, avoiding confusion.

Naming Consistency4/5

Tool names follow a verb_noun pattern with clear resource identification. Minor inconsistencies exist, such as mixing 'create' and 'save' for creating/overwriting files, and inconsistent pluralization (e.g., delete_crons vs delete_script), but these do not undermine predictability.

Tool Count3/5

At 42 tools, the set is large, but it reflects the multi-faceted nature of Qinglong (crons, envs, scripts, subscriptions, configs, dependencies, system). While it exceeds the ideal range, most tools earn their place, though some consolidation could reduce bloat.

Completeness4/5

The surface provides comprehensive coverage for most resources with full CRUD and lifecycle operations. However, subscriptions lack update and delete operations, and there is no single-get for cron tasks, though list_crons provides the data. Minor gaps exist but agents can work around them.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

mcp-aichat
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2
https://aichat.mcp.acedata.cloud/mcp
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
https://api.microservices.sh/mcp
mcp-openai
io.github.AceDataCloud
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
AI & Machine Learning Image & Video Processing
11
https://openai.mcp.acedata.cloud/mcp
supportsheep
io.github.pooriaarab
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Customer Support Content Management Systems Marketing
1
https://supportsheep.com/api/v1/mcp

Related MCP Servers

bt-panel-mcp-server
Observability File Systems Cloud Platforms
SuxyEE
A
license
A
quality
D
maintenance
This MCP server enables AI assistants to interact with a BT Panel server through natural language, allowing users to query logs, manage websites, and monitor system status without manual panel login.
Updated 3 months ago (2026-08-03 09:12 UTC)
9
31 npm
12
MIT
easypanel-mcp
Cloud Platforms Databases Monitoring
dray-supadev
A
license
B
quality
C
maintenance
MCP server for EasyPanel that enables AI agents to manage servers, projects, services, databases, and domains via 40 curated tools or raw tRPC access to all 347 API procedures.
Updated 2 months ago (2026-08-27 20:51 UTC)
42
35 npm
4
MIT
agileconfig-mcp-server
Developer Tools App Automation
animacaeli
A
license
A
quality
D
maintenance
MCP server that exposes all AgileConfig RESTful APIs as tools, enabling AI assistants to manage configuration, applications, users, nodes, and more via natural language.
Updated 4 months ago (2026-07-07 01:20 UTC)
36
11 npm
MIT
mcp-1panel
Developer Tools Virtualization Databases
Guoyin-Wen
A
license
Not graded
quality
D
maintenance
Full-featured MCP server for 1Panel server management panel. Provides 490+ tools for managing websites, databases, containers, files, and more through natural language.
Updated 4 months ago (2026-07-25 01:33 UTC)
MIT

qinglong-mcp

目录

功能特性

安装

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

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

快速开始

1. 准备青龙凭证

2. 客户端配置（stdio）

3. 使用示例

环境变量

工具清单

传输模式

stdio（默认，推荐）

Streamable HTTP（多 agent 远程共享）

开发与测试

安全提示

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

bt-panel-mcp-server

easypanel-mcp

agileconfig-mcp-server

mcp-1panel