Jenkins MCP Server

Jenkins MCP服务器

](https://badge.fury.io/js/@ashwinighuge%2Fjenkins-mcp-server) 

用于无缝Jenkins CI/CD集成的企业级MCP（模型上下文协议）服务器。使像Claude这样的人工智能助手能够通过全面的、可生产的API与Jenkins互动。

🚀 快速开始

npm安装（推荐）

# Global installation
npm install -g @ashwinighuge/jenkins-mcp-server

# Or use directly with npx
npx @ashwinighuge/jenkins-mcp-server --help

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "jenkins-mcp",
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

✨ 特性

• 🔧 作业管理：触发、列出、搜索和监视具有完整文件夹支持的Jenkins作业
• 📊 生成状态：实时构建状态跟踪和控制台日志流
• 🔄 管道支架：使用详细日志进行分阶段管道执行监控
• 📦 工件管理：跨多个构建列出、下载和搜索构建工件
• ⚡ 批量操作：具有智能优先级队列的并行作业执行
• 🚀 性能缓存：多层智能缓存系统，自动失效
• 🔍 高级过滤：使用正则表达式支持按状态、结果、日期等筛选作业
• 📋 队列管理：实时构建队列监控和管理
• 🔒 企业安全：CSRF保护、2FA支持和安全身份验证
• 🌐 交叉平台的：适用于Windows、macOS和Linux
• 🔄 重试逻辑：内置指数回退，提高可靠性
• 📡 运输灵活性：支持STDIO和HTTP传输
• ✅ 输入验证：基于Pydantic的强大验证和错误处理

📋 先决条件

• Node.js：14.0.0或更高
• python：3.12或更高
• 詹金斯：2.401+（推荐）
• Jenkins API代币：用于身份验证

🛠 安装方法

方法1:npm（推荐）

# Install globally for system-wide access
npm install -g @ashwinighuge/jenkins-mcp-server

# Verify installation
jenkins-mcp --help

方法2：开发设置

# Clone the repository
git clone https://github.com/AshwiniGhuge3012/jenkins-mcp-server
cd jenkins-mcp-server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt  # or use uv pip install

# Run locally
node bin/jenkins-mcp.js --help

🔐 配置

环境变量

创建一个 .env 工作目录中的文件：

# Required Jenkins Configuration
JENKINS_URL="http://your-jenkins-server:8080"
JENKINS_USER="your-username"
JENKINS_API_TOKEN="your-api-token"

# Optional: Server Configuration
MCP_PORT=8010
MCP_HOST=0.0.0.0

# Optional: Retry Configuration
JENKINS_MAX_RETRIES=3
JENKINS_RETRY_BASE_DELAY=1.0
JENKINS_RETRY_MAX_DELAY=60.0
JENKINS_RETRY_BACKOFF_MULTIPLIER=2.0

# Optional: Performance Cache Configuration
JENKINS_CACHE_STATIC_TTL=3600        # 1 hour
JENKINS_CACHE_SEMI_STATIC_TTL=300    # 5 minutes
JENKINS_CACHE_DYNAMIC_TTL=30         # 30 seconds
JENKINS_CACHE_SHORT_TTL=10           # 10 seconds
JENKINS_CACHE_STATIC_SIZE=1000       # Max cached items
JENKINS_CACHE_SEMI_STATIC_SIZE=500
JENKINS_CACHE_DYNAMIC_SIZE=200
JENKINS_CACHE_PERMANENT_SIZE=2000
JENKINS_CACHE_SHORT_SIZE=100

获取Jenkins API令牌

1. 登录您的Jenkins实例
2. 点击您的用户名→ 配置
3. 滚动到 API代币 章节
4. 点击 添加新令牌
5. 给它起个名字，然后单击 生成
6. 复制生成的令牌（安全保存！）

🚀 用法

命令行接口

# STDIO mode (default, for Claude Desktop)
jenkins-mcp

# HTTP mode (for MCP Gateway)
jenkins-mcp --transport streamable-http --port 8010

# Custom host and port
jenkins-mcp --transport streamable-http --host localhost --port 9000

# Show help
jenkins-mcp --help

运输方式

高级使用示例

# Using with npx (no global installation)
npx @ashwinighuge/jenkins-mcp-server

# Using environment variables
JENKINS_URL=http://localhost:8080 JENKINS_USER=admin JENKINS_API_TOKEN=abc123 jenkins-mcp

# HTTP mode with custom configuration
jenkins-mcp --transport streamable-http --host 0.0.0.0 --port 8080

可用工具

以下是此MCP服务器公开的工具列表：

trigger_job

• 描述：使用可选参数触发Jenkins作业。
• 参数:

- job_name （string）：Jenkins作业的名称。 - params （object，可选）：作业参数为JSON对象。对于多选参数，传递一个字符串数组。

• 退货：带有队列URL的确认消息。

get_job_info

• 描述：获取有关Jenkins作业的详细信息，包括其参数。
• 参数:

- job_name （string）：Jenkins作业的名称。

• 退货：一个包含作业描述、参数和上次生成号的对象。

get_build_status

• 描述：获取特定生成的状态。
• 参数:

- job_name （string）：Jenkins作业的名称。 - build_number （整数）：内部版本号。

• 退货：一个具有构建状态、时间戳、持续时间和URL的对象。

get_console_log

• 描述：检索特定版本的控制台日志。
• 参数:

- job_name （string）：Jenkins作业的名称。 - build_number （整数）：内部版本号。 - start （整数，可选）：获取日志的起始字节位置。

• 退货：控制台日志文本和有关是否有更多数据可用的信息。

list_jobs

• 描述：列出Jenkins服务器上具有高级过滤功能的所有可用作业。
• 参数:

- recursive （布尔值，可选）：如果为True，则递归遍历文件夹（默认值：True） - max_depth （整数，可选）：递归的最大深度（默认值：10） - include_folders （布尔值，可选）：是否包含文件夹项（默认值：False） - status_filter （字符串，可选）：按作业状态筛选：“正在构建”、“已排队”、“空闲”、“禁用” - last_build_result （字符串，可选）：按上次构建结果筛选：“SUCCESS”、“FAILURE”、“UNSTABLE”、“ABORTED”、“NOT_BUILT” - days_since_last_build （整数，可选）：仅在过去N天内构建的作业 - enabled_only （布尔值，可选）：如果为True，则仅启用作业；如果为False，则仅禁用作业

• 退货：具有增强元数据的作业列表，包括构建状态和时间戳。

search_jobs

• 描述：使用模式匹配和高级过滤搜索Jenkins作业。
• 参数:

- pattern （string）：匹配作业名称的模式（支持通配符，如“build\*”、“*测试*等等） - job_type （字符串，可选）：按类型筛选-“作业”、“文件夹”或“全部”（默认值：“作业”） - max_depth （整数，可选）：要搜索的最大深度（默认值：10） - use_regex （boolean，可选）：如果为True，则将模式视为正则表达式而不是通配符（默认值：False） - status_filter （字符串，可选）：按作业状态筛选：“正在构建”、“已排队”、“空闲”、“禁用” - last_build_result （字符串，可选）：按上次构建结果筛选：“SUCCESS”、“FAILURE”、“UNSTABLE”、“ABORTED”、“NOT_BUILT” - days_since_last_build （整数，可选）：仅在过去N天内构建的作业 - enabled_only （布尔值，可选）：如果为True，则仅启用作业；如果为False，则仅禁用作业

• 退货：具有增强元数据和完整路径的匹配作业列表。

get_queue_info

• 描述：获取队列中当前生成的信息。
• 参数：无
• 退货：队列中的项目列表。

server_info

• 描述：获取有关Jenkins服务器的基本信息。
• 参数：无
• 退货：Jenkins版本和URL。

get_pipeline_status

• 描述：获取Jenkins pipeline作业构建的详细管道阶段状态。
• 参数:

- job_name （string）：Jenkins Pipeline作业的名称。 - build_number （整数）：内部版本号。

• 退货：管道执行详细信息，包括阶段状态、时间、持续时间和日志。

list_build_artifacts

• 描述：列出特定Jenkins构建的所有工件。
• 参数:

- job_name （string）：Jenkins作业的名称。 - build_number （整数）：用于列出工件的内部版本号。

• 退货：有关所有工件的信息，包括文件名、大小和下载URL。

download_build_artifact

• 描述：下载特定的构建工件内容（仅出于安全考虑，基于文本的工件）。
• 参数:

- job_name （string）：Jenkins作业的名称。 - build_number （整数）：包含工件的内部版本号。 - artifact_path （string）：工件的相对路径（来自list_build_artifacts）。 - max_size_mb （整数，可选）：下载的最大文件大小（MB）（默认值：50MB）。

• 退货：工件内容（用于文本文件）或下载信息。

search_build_artifacts

• 描述：使用模式匹配在作业的最新版本中搜索工件。
• 参数:

- job_name （string）：要搜索的Jenkins作业的名称。 - pattern （string）：匹配工件名称的模式（通配符或正则表达式）。 - max_builds （整数，可选）：要搜索的最新版本的最大数量（默认值：10）。 - use_regex （布尔值，可选）：如果为True，则将模式视为正则表达式而不是通配符（默认值：False）。

• 退货：跨构建的匹配工件列表及其元数据。

batch_trigger_jobs

• 描述：通过并行执行和优先级队列批量触发多个Jenkins作业。
• 参数:

- operations （array）：作业操作列表，每个操作包含： - job_name （string）：Jenkins作业的名称 - params （对象，可选）：作业参数 - priority （整数，可选）：优先级1-10（1=最高，默认值：1） - max_concurrent （整数，可选）：最大并发作业触发器（默认值：5） - fail_fast （布尔值，可选）：第一次失败时停止处理（默认值：false） - wait_for_completion （布尔值，可选）：等待所有作业完成（默认值：false）

• 退货：带有操作ID、结果和执行统计信息的批处理操作响应。

batch_monitor_jobs

• 描述：监视批处理操作及其单个作业的状态。
• 参数:

- operation_id （string）：从batch_trigger_jobs返回的操作ID。

• 退货：批处理操作的当前状态，包括进度和单个作业状态。

batch_cancel_jobs

• 描述：取消批处理操作，并可选择取消正在运行的构建。
• 参数:

- operation_id （string）：要取消的操作ID。 - cancel_running_builds （布尔值，可选）：尝试取消正在运行的构建（默认值：false）。

• 退货：取消状态和结果。

get_cache_statistics

• 描述：获取全面的缓存性能指标和利用率统计数据。
• 参数：无
• 退货：所有缓存类型的缓存命中率、利用率百分比和详细统计信息。

clear_cache

• 描述：通过细粒度控制清除缓存以进行性能管理。
• 参数:

- cache_type （字符串，可选）：要清除的缓存类型（“all”、“static”、“semi_static”、“动态”、“永久”、“short”） - job_name （字符串，可选）：仅清除特定作业的缓存

• 退货：确认缓存清除操作。

warm_cache

• 描述：将频繁访问的数据预加载到缓存中以提高性能。
• 参数:

- operations （数组，可选）：要预热的操作（'server_info'，'job_list'，'queue_info'）

• 退货：缓存预热操作的结果，状态为成功/失败。

summarize_build_log

• 描述：（演示）使用预配置的LLM提示符总结生成日志。
• 参数:

- job_name （string）：Jenkins作业的名称。 - build_number （整数）：内部版本号。

• 退货：占位符摘要和将使用的提示。

💡 使用示例

使用克劳德桌面

配置后 claude_desktop_config.json你可以问克劳德：

“列出所有Jenkins作业” “使用版本参数1.2.3触发部署prod作业” “显示api测试作业版本#45的控制台日志” “过去24小时内失败的所有作业的状态如何？”

使用MCP网关

# Start server in HTTP mode
jenkins-mcp --transport streamable-http --port 8010

# Example API calls (using curl)
curl -X POST http://localhost:8010/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "list_jobs", "arguments": {}}}'

批量操作示例

# Trigger multiple jobs with different priorities
jenkins-mcp # Then use batch_trigger_jobs tool with:
{
  "operations": [
    {"job_name": "unit-tests", "priority": 1},
    {"job_name": "integration-tests", "priority": 2},
    {"job_name": "deploy-staging", "priority": 3}
  ],
  "max_concurrent": 3,
  "wait_for_completion": true
}

🔧 故障排除

常见问题

Python依赖关系

# If Python packages fail to install automatically
pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

# Or using uv (recommended)
uv pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

权限问题（Linux/macOS）

# If permission denied
sudo npm install -g @ashwinighuge/jenkins-mcp-server

# Or use user-level installation
npm install -g @ashwinighuge/jenkins-mcp-server --prefix ~/.local

Jenkins连接问题

• 验证 JENKINS_URL 可访问
• 确保API令牌有效且未过期
• 检查防火墙/代理设置
• 对于HTTPS，验证SSL证书

2FA/CSRF问题

• 服务器自动处理CSRF令牌
• 对于2FA环境，请使用API令牌（而不是密码）
• 支持电子邮件OTP和类似的2FA方法

调试模式

# Enable verbose logging
DEBUG=jenkins-mcp jenkins-mcp

# Check Python dependencies
jenkins-mcp --help  # Will validate dependencies

📊 性能特点

• 多层缓存：具有自动失效功能的智能缓存
• 批处理：具有优先级队列的并行作业执行
• 重试逻辑：网络可靠性的指数回退
• 连接池：高效的HTTP连接管理
• 内存优化：可配置的缓存大小和TTL值

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 提交更改： git commit -m 'Add amazing feature'
4. 推送到分支： git push origin feature/amazing-feature
5. 打开拉取请求

📄 许可证

此项目根据Apache 2.0许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙋‍♂️ 支持

• 文档:
• 问题:
• npm包: @ashwinighuge/jenkins mcp服务器

🏗️ 建筑

内置：

• Python 3.12+ -核心服务器实施
• FastMCP -MCP协议处理
• Node.js -跨平台包装和流程管理
• 派丹蒂克 -数据验证和序列化
• 请求： -具有重试逻辑的HTTP客户端
• 缓存工具 -多层性能缓存

______________________________________________________________________