xxl-job-mcp

面向 XXL-Job 调度中心（Admin Web）的 Model Context Protocol 服务：在 Cursor 等客户端里用自然语言或工具参数完成「登录校验 / 立即触发 / 启停调度 / 查任务列表」。

安装（npm 发布后）

说明：npm install / npx 只会把包下载到本机，Cursor 不会自动修改你的 mcp.json，也没有「安装完就在设置里凭空出现三个输入框」的官方机制。
要实现「配置里自动带出三个字段名（XXL_JOB_BASE_URL / XXL_JOB_USERNAME / XXL_JOB_PASSWORD）」，请用下面任一方式。

方式 A（推荐）：一条命令生成带 env 三字段的片段

安装或直接使用 npx 后执行：

npx xxl-job-mcp init

• 终端 stdout 会输出一段可直接合并进 mcp.json 的 JSON（已包含上述 三个 env 键，type: "stdio" 与 npx 启动方式）。
• 若本机还没有 %USERPROFILE%\.xxl-job-mcp.env，会按 xxl-job-mcp.env.example 自动生成模板（便于把密码只放在该文件里）。

把输出的 xxl-job 段粘贴到 %USERPROFILE%\.cursor\mcp.json（或项目 .cursor/mcp.json）的 mcpServers 中，保存后重启 Cursor 即可。

方式 B：手写最小配置（不在 mcp.json 里写密码）

在 Cursor Settings → Tools & MCPs 里新增 MCP，例如：

{
  "mcpServers": {
    "xxl-job": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "xxl-job-mcp@latest"]
    }
  }
}

把账号密码写到 %USERPROFILE%\.xxl-job-mcp.env（或系统用户环境变量），详见下文「凭据放哪里」。此方式 mcp.json 里不会出现三个键，但 Cursor 仍会通过进程环境把变量传给 MCP。

在 mcp.json 里显式写三个配置字段（可选）

若你希望像本地调试一样，把连接信息直接写在 Cursor 的 env 里，至少需要下面 三个字段（名称固定，程序里按这个读）：

| env 键 | 含义 | |----------|------| | XXL_JOB_BASE_URL | 调度中心 Admin 根地址（含 context-path，如 .../xxl-job 或 .../xxl-job-admin） | | XXL_JOB_USERNAME | 登录用户名（也可用别名 XXL_JOB_USER） | | XXL_JOB_PASSWORD | 登录密码 |

示例见仓库根目录 cursor-mcp.example.json（复制到全局/项目 mcp.json 的 mcpServers 中后，改成你的真实地址与密码即可）。注意：密码写在 mcp.json 里容易随配置备份泄露，生产环境更推荐下面的「凭据放哪里」。

使用本仓库源码启动时，把 command / args 换成你的本机路径即可，env 里同样是这三个字段，例如：

{
  "mcpServers": {
    "xxl-job": {
      "command": "node",
      "args": ["E:/wjztestprotect/xxl-job-mcp/src/index.js"],
      "env": {
        "XXL_JOB_BASE_URL": "http://你的调度中心域名/xxl-job",
        "XXL_JOB_USERNAME": "admin",
        "XXL_JOB_PASSWORD": "请填写登录密码"
      }
    }
  }
}

凭据放哪里（按推荐顺序）

1. 用户目录下的 env 文件（推荐）
   在本机创建文件：%USERPROFILE%\.xxl-job-mcp.env（macOS/Linux：~/.xxl-job-mcp.env），内容示例见仓库里的 xxl-job-mcp.env.example。

2. 自定义路径
   设置环境变量 XXL_JOB_ENV_FILE 指向你的密钥文件（仍可不写进 mcp.json：可在操作系统「用户环境变量」里配置该变量）。

3. 操作系统用户环境变量
   把 XXL_JOB_BASE_URL / XXL_JOB_USERNAME / XXL_JOB_PASSWORD 配到系统里；mcp.json 里同样可以不出现密码。

4. 仅调试
   也可以在 mcp.json 的 env 里临时写变量（不推荐，容易泄露）。

说明：密钥文件中的变量 不会覆盖 已存在的环境变量，方便你在本机用系统变量覆盖默认值。

环境变量

| 变量 | 必填 | 说明 | |------|------|------| | XXL_JOB_BASE_URL | 是 | Admin 根地址，需包含 context-path，如 http://host:8080/xxl-job-admin 或 http://host/xxl-job | | XXL_JOB_USERNAME | 是 | 登录用户名（别名 XXL_JOB_USER） | | XXL_JOB_PASSWORD | 是 | 登录密码 | | XXL_JOB_ENV_FILE | 否 | 指定 .env 文件路径 |

MCP 工具一览

• xxl_login_check：登录校验
• xxl_trigger_job：按任务 ID 立即触发一次
• xxl_list_jobs：分页查询任务
• xxl_start_job / xxl_stop_job：启停调度
• xxl_auto_dispatch：传入用户原话，自动识别动作并触发（多匹配时会返回候选列表）

本地开发

cd xxl-job-mcp
npm install
npm start

发布到 npm（维护者）

cd xxl-job-mcp
npm login
npm publish --access public

若本机 npm 镜像为 npmmirror 等，需要发布到 npmjs 官方源时可显式指定：

npm publish --registry https://registry.npmjs.org/

首次发布前请确认包名 xxl-job-mcp 在 npm 上未被占用；若需改名，修改 package.json 的 name 后再发。

许可

MIT