# Jenkins MCP Server

TypeScript MCP server that connects AI agents to Jenkins. Supports **stdio** and **Streamable HTTP** transports, plus a local web UI to test credential authentication/authorization and copy agent configuration snippets.

**Developed by [oshaani.com](https://oshaani.com)** · © oshaani.com. All rights reserved.

## Features

- MCP tools for jobs, builds, logs, queue, nodes, identity, and auth checks
- **stdio** mode for Cursor, Claude Desktop, VS Code
- **HTTP** mode with Streamable MCP endpoint at `/mcp`
- Web UI to test Jenkins username/API token auth and permission probes
- Ready-made config snippets for AI agents
- Unit tests with Vitest

## Quick start

```bash
npm install
npm run build
cp .env.example .env   # then edit credentials
```

### Local Jenkins in Docker (recommended for testing)

```bash
docker compose up -d
# Wait until healthy, then copy the generated API token into .env:
docker exec jenkins-mcp-test cat /var/jenkins_home/mcp-api-token.txt
```

Default test login:

| Field | Value |
| --- | --- |
| URL | http://127.0.0.1:8080 |
| Username | `admin` |
| Password | `admin123` |
| Sample job | `hello-mcp` |

Put the token from `mcp-api-token.txt` into `.env` as `JENKINS_API_TOKEN`, then:

```bash
npm run start:http
```

Open [http://127.0.0.1:3100](http://127.0.0.1:3100) and run **Test authentication**.

Stop Jenkins later with `docker compose down` (add `-v` to wipe data).

### HTTP + UI

```bash
npm run start:http
```

Open [http://127.0.0.1:3100](http://127.0.0.1:3100) to:

1. Test authentication and authorization against your Jenkins
2. Copy MCP config for Cursor / Claude Desktop / VS Code

### Stdio (AI agents)

```bash
npm run start:stdio
```

## Environment

| Variable | Description |
| --- | --- |
| `JENKINS_URL` | Jenkins base URL |
| `JENKINS_USERNAME` | Jenkins username |
| `JENKINS_API_TOKEN` | Jenkins API token |
| `PORT` / `MCP_HTTP_PORT` | HTTP port (default `3100`) |
| `MCP_HTTP_HOST` | Bind host (default `127.0.0.1`) |
| `JENKINS_READ_ONLY` | `true` disables `jenkins_trigger_build` |

## Cursor MCP config (stdio)

```json
{
  "mcpServers": {
    "jenkins": {
      "command": "node",
      "args": ["/absolute/path/to/Jenkins MCP/dist/index.js", "stdio"],
      "env": {
        "JENKINS_URL": "https://jenkins.example.com",
        "JENKINS_USERNAME": "your-user",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Cursor MCP config (HTTP + headers)

Pass Jenkins credentials from the agent on every request:

```json
{
  "mcpServers": {
    "jenkins": {
      "url": "http://127.0.0.1:3100/mcp",
      "headers": {
        "X-Jenkins-Url": "http://127.0.0.1:8080",
        "X-Jenkins-Username": "admin",
        "X-Jenkins-Api-Token": "your-api-token"
      }
    }
  }
}
```

Header values override server `.env` for that MCP session. You can also use `Authorization: Basic base64(username:apiToken)` plus `X-Jenkins-Url`.

### Cursor MCP config (HTTP + server env)

```json
{
  "mcpServers": {
    "jenkins": {
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}
```

## MCP tools

| Tool | Description |
| --- | --- |
| `jenkins_whoami` | Authenticated user identity |
| `jenkins_test_auth` | Auth + authorization permission probes |
| `jenkins_list_jobs` | List visible jobs |
| `jenkins_get_job` | Job details |
| `jenkins_get_build` | Build details |
| `jenkins_get_build_log` | Progressive console log |
| `jenkins_get_queue` | Build queue |
| `jenkins_get_nodes` | Agents/nodes |
| `jenkins_trigger_build` | Trigger build (disabled in read-only mode) |

## Development

```bash
npm test
npm run typecheck
npm run dev
```

## License

MIT

Copyright © oshaani.com. Developed by [oshaani.com](https://oshaani.com). All rights reserved.