# qinglong-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/Node-%3E%3D18-339933)](https://nodejs.org)

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

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

## 目录

- [功能特性](#功能特性)
- [安装](#安装)
- [快速开始](#快速开始)
- [环境变量](#环境变量)
- [工具清单](#工具清单)
- [传输模式](#传输模式)
- [开发与测试](#开发与测试)
- [安全提示](#安全提示)
- [License](#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 会自动完成安装与注册，**全程无需你手动指定任何路径**：

```text
请帮我自动安装并接入 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. 完成后用「列出青龙的定时任务」验证连通，并报告安装路径与配置位置
```

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

```bash
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/](examples/)：**WorkBuddy / Claude Desktop / Codex / OpenCode**。

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

```json
{
  "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**：

```bash
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` 中：

```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 远程共享）

```bash
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 连接：

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

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

## 开发与测试

```bash
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](LICENSE) © 2026 YSJohnson