Skip to main content
Glama

mcp-xxl-job

npm version License: MIT Node.js >= 18

MCP Server for XXL-JOB Admin — 通过 MCP 协议让 AI 助手直接管理 XXL-JOB 定时任务。

GitHub Repository:mcp‑xxl‑job

✅ This MCP server is indexed on Glama.ai

功能特性

  • 执行器组管理 — 查询执行器组列表及在线机器地址

  • 任务全生命周期 — 查询、新增、修改、删除、启动、停止定时任务

  • 手动触发执行 — 支持覆盖运行参数、指定执行器地址

  • 调度预演 — 根据 Cron 表达式预演未来触发时间

  • 执行日志 — 分页查询调度记录,增量拉取日志正文

  • 安全设计 — 自动登录、Cookie 会话维护、失效自动重登

  • 防字段丢失 — 修改任务采用「读取-合并-写回」策略

Related MCP server: rundeck-mcp-server

提供的 MCP 工具

工具

功能

list_job_groups

分页查询执行器组列表

list_jobs

分页查询任务列表(支持按执行器组、状态、描述等过滤)

get_job

查询单个任务完整配置

add_job

新增任务(支持 CRON / FIX_RATE / NONE 调度类型)

update_job

修改任务配置(未传入字段保持原值)

remove_job

删除任务

start_job

启动任务调度

stop_job

停止任务调度

trigger_job

手动触发一次执行

preview_next_trigger_times

预演未来触发时间

list_job_logs

分页查询执行日志

get_job_log_content

增量拉取日志正文

环境要求

  • Node.js >= 18

  • XXL-JOB Admin >= 2.3.0

配置

环境变量

变量

必填

说明

XXL_JOB_URL

✅

调度中心地址,如 http://127.0.0.1:8080/xxl-job-admin

XXL_JOB_USERNAME

✅

登录用户名

XXL_JOB_PASSWORD

✅

登录密码

XXL_JOB_TIMEOUT_MS

❌

HTTP 超时(毫秒),默认 15000

MCP 客户端配置

在 MCP 客户端(如 Claude Desktop、Cursor、Qoder 等)中添加以下配置:

方式一:全局安装后使用(推荐)

  • 安装:

npm install -g mcp-xxl-job

升级:全局安装的版本不会自动更新,需手动升级:

npm update -g mcp-xxl-job
# 或
npm install -g mcp-xxl-job@latest
  • 配置:

{
  "mcpServers": {
    "xxl-job": {
      "command": "mcp-xxl-job",
      "env": {
        "XXL_JOB_URL": "http://127.0.0.1:8080/xxl-job-admin",
        "XXL_JOB_USERNAME": "admin",
        "XXL_JOB_PASSWORD": "123456"
      }
    }
  }
}

方式二:通过 npx 使用

注意:如果你的 npm 配置了国内镜像源(如 npmmirror),npx 可能无法找到包。此时请使用全局安装方式,或指定官方源:

npx --registry=https://registry.npmjs.org mcp-xxl-job@latest

包名后加 @latest 可确保每次启动都获取最新版本(npx 有本地缓存,不加 @latest 可能会一直使用缓存的旧版本)。

  • 配置:

{
  "mcpServers": {
    "xxl-job": {
      "command": "npx",
      "args": ["-y", "mcp-xxl-job@latest"],
      "env": {
        "XXL_JOB_URL": "http://127.0.0.1:8080/xxl-job-admin",
        "XXL_JOB_USERNAME": "admin",
        "XXL_JOB_PASSWORD": "123456"
      }
    }
  }
}

提示:如果 npx 方式连接失败,请改用全局安装方式,或在 args 中添加 "--registry=https://registry.npmjs.org"。

使用示例

配置完成后,你可以用自然语言让 AI 助手操作 XXL-JOB:

查询当前有哪些定时任务
新增一个任务:执行器组=demo-server,描述=数据同步,Cron=0 0 2 * * ? *,Handler=syncJobHandler
停止任务 id=5 的调度
查看任务 id=3 最近 10 条执行日志
预演 Cron 表达式 0 0/30 * * * ? 的未来触发时间

开发

# 克隆项目
git clone https://github.com/shaguocgl/mcp-xxl-job.git
cd mcp-xxl-job

# 安装依赖
npm install

# 编译
npm run build

# 运行
npm start

# 开发模式(自动重新编译)
npm run dev

测试

# 冒烟测试
npm run smoke

# 集成测试(需要可用的 XXL-JOB 实例)
npm run test:integration

# 客户端单元测试
npm run test:client

项目结构

mcp-xxl-job/
├── src/
│   ├── server.ts      # MCP 服务入口,注册所有工具
│   ├── client.ts      # XXL-JOB Admin HTTP 客户端
│   ├── config.ts      # 环境变量配置加载
│   └── models.ts      # 数据结构与校验逻辑
├── tests/
│   ├── smoke.ts       # 冒烟测试
│   ├── integration.ts # 集成测试
│   ├── test-client.ts # 客户端测试
│   └── mock-admin.ts  # Mock 服务器
├── package.json
├── tsconfig.json
└── .env.example       # 环境变量示例

技术栈

  • Runtime: Node.js >= 18

  • Language: TypeScript

  • MCP SDK: @modelcontextprotocol/sdk

  • Schema Validation: Zod

  • Transport: stdio

许可证

MIT © 2026

Available Tools

12 tools
add_job新增任务A

在 XXL-JOB 中新增一个任务。必填:执行器组 id、任务描述、调度类型与配置、JobHandler。未提供的可选项使用默认值:路由策略 FIRST、阻塞策略 SERIAL_EXECUTION、过期策略 DO_NOTHING、运行模式 BEAN。新增后默认为停止状态,可用 start_job 启动。

Inputs: jobDesc (required), jobGroup (required), scheduleType (required), executorHandler (required), +10 more.

get_job查询任务详情A

根据任务 id 查询 XXL-JOB 任务的完整配置详情。

Inputs: jobId (required).

get_job_log_content查看执行日志正文A

增量拉取某条执行记录的日志正文(来自执行器)。logId、executorAddress、triggerTime 取自 list_job_logs 的返回。日志较长时,用返回的 toLineNum+1 作为下一次 fromLineNum 继续读取,直到 isEnd=true。

Inputs: logId (required), triggerTime (required), executorAddress (required), fromLineNum.

list_job_groups查询执行器组列表A

分页查询 XXL-JOB 的执行器组(执行器)列表,返回 id、AppName、名称、注册方式、在线机器地址等信息。新增任务前通常需要先查执行器组 id。

Inputs: page, title, appname, pageSize.

list_job_logs查询执行日志列表A

分页查询任务的执行日志(调度记录),支持按执行器组、任务、执行状态、调度时间范围过滤。返回每条记录的调度结果(triggerCode)、执行结果(handleCode)、执行器地址与触发时间,可据此调用 get_job_log_content 查看日志正文。

Inputs: page, jobId, jobGroup, pageSize, +3 more.

list_jobs分页查询任务列表A

分页查询 XXL-JOB 任务列表,支持按执行器组、调度状态(0=停止/1=运行中)、任务描述、JobHandler、负责人过滤。

Inputs: page, author, jobDesc, jobGroup, +3 more.

preview_next_trigger_times预演未来触发时间A

根据调度类型与配置(如 Cron 表达式)预演未来若干次触发时间,用于校验调度配置是否符合预期。

Inputs: scheduleConf (required), scheduleType (required).

remove_job删除任务A

永久删除指定任务(不可恢复,任务配置与历史日志将一并清除)。

Inputs: jobId (required).

start_job启动任务B

启动指定任务的调度(使其按调度配置自动执行)。

Inputs: jobId (required).

stop_job停止任务A

停止指定任务的调度(不再自动执行,历史配置保留)。

Inputs: jobId (required).

trigger_job手动触发一次执行A

手动触发指定任务立即执行一次(不影响原有调度状态)。可覆盖运行参数,也可指定执行器地址列表(为空则按任务配置的路由策略选择)。

Inputs: jobId (required), addressList, executorParam.

update_job修改任务A

修改 XXL-JOB 任务配置。采用先读取现有全量配置、合并本次变更、再整体提交的方式,未传入的字段保持原值不变。调度状态(启动/停止)请用 start_job / stop_job,不在此工具处理。

Inputs: jobId (required), author, jobDesc, jobGroup, +11 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct operation on a distinct resource: job configs, job groups, schedules, and logs. Tools like trigger_job vs start_job and update_job vs start/stop are clearly differentiated by their descriptions, leaving no ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using lowercase snake_case (e.g., get_job, list_jobs, start_job, remove_job). The pattern is uniform across the entire set, with only minor variation in noun plurality that does not affect predictability.

    Tool Count5/5

    With 12 tools, the server is well-scoped for its purpose. Each tool covers a necessary operation in the XXL-JOB workflow without redundancy or excessive granularity.

    Completeness5/5

    The tool set provides full lifecycle coverage for job management: create, read, update, delete, start/stop, manual trigger, schedule preview, and log retrieval. No significant gaps are apparent for the stated domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for scheduling and executing Claude Code CLI tasks via cron expressions, featuring a web dashboard and webhook support. It enables users to dynamically create custom MCP servers, manage recurring AI jobs, and track execution history with token and cost analytics.
      24
      MIT
    • 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.
      36
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that lets AI agents manage cron jobs through natural language — adding, listing, pausing, removing, running, and viewing logs of scheduled jobs with plain-English schedule parsing, automatic log capture, missed-run detection, and failure alerts.
      MIT