mcp-xxl-job
This server allows AI assistants to manage XXL-JOB scheduled tasks and executors via natural language. Key capabilities include:
Executor Group Management: List executor groups with details like ID, AppName, and online addresses.
Job Lifecycle: List, query, add, update (with intelligent field merge), delete, start, and stop scheduled jobs.
Manual Execution & Scheduling Preview: Trigger jobs immediately with optional parameter overrides; preview future trigger times for cron or fixed-rate schedules.
Logging & Monitoring: Query execution logs with filters (by job, status, time range); retrieve log content incrementally.
Configuration: Secure auto-login and session maintenance; update jobs without losing unspecified fields.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-xxl-job 查询当前有哪些定时任务"
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.
mcp-xxl-job
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 工具
工具 | 功能 |
| 分页查询执行器组列表 |
| 分页查询任务列表(支持按执行器组、状态、描述等过滤) |
| 查询单个任务完整配置 |
| 新增任务(支持 CRON / FIX_RATE / NONE 调度类型) |
| 修改任务配置(未传入字段保持原值) |
| 删除任务 |
| 启动任务调度 |
| 停止任务调度 |
| 手动触发一次执行 |
| 预演未来触发时间 |
| 分页查询执行日志 |
| 增量拉取日志正文 |
环境要求
Node.js >= 18
XXL-JOB Admin >= 2.3.0
配置
环境变量
变量 | 必填 | 说明 |
| ✅ | 调度中心地址,如 |
| ✅ | 登录用户名 |
| ✅ | 登录密码 |
| ❌ | 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 toolsadd_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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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.24MIT
- AlicenseNot gradedqualityDmaintenanceMCP server enabling AI assistants to manage Rundeck projects, jobs, and executions through a standardized interface.MIT
- AlicenseAqualityDmaintenanceMCP server that exposes all AgileConfig RESTful APIs as tools, enabling AI assistants to manage configuration, applications, users, nodes, and more via natural language.368 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn 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