netlinq-jenkins-mcp
netlinq-jenkins-mcp
Ein kleiner Python-Dienst, der Ihren privaten Jenkins-Controller umschließt und es einem Team ermöglicht, die Jobs NetLinQ EMS Release pipeline und Patch Single Repository Pipeline durch natürliche Sprache auszulösen. Eine Codebasis, zwei Ausführungsmodi:
MCP-Server (stdio) - in Cursor auf Ihrem Laptop einbinden und fragen: "build 7.0 release package" oder "rebuild blinq-ems-charts at tag 7.0.3".
FastAPI-Web-App + Chat-UI - ein Befehl
docker compose upauf einem internen Server, das gesamte Team loggt sich über den Browser ein und erhält dieselben Tools.
Hosting-Hinweis: GitHub-gehostete Runner können keinen privaten Jenkins erreichen. Der Code liegt in einem privaten GitHub-Repo; die Laufzeit läuft dort, wo sie einen Netzwerkpfad zu Jenkins hat (der Laptop eines Teammitglieds mit VPN oder eine interne Linux-VM).
Inhaltsverzeichnis
Related MCP server: MCP-Jenkins
Architektur
flowchart LR
subgraph github [Private GitHub Repo]
repo[netlinq-jenkins-mcp]
end
subgraph local [Local laptop - DevOps user]
cursor[Cursor IDE]
mcp["FastMCP stdio server<br/>mcp_server.py"]
cursor -->|stdio| mcp
end
subgraph shared [Internal VM - team]
web["FastAPI web app<br/>web.py + Vite UI"]
chat["Chat UI - browser"]
chat -->|HTTPS basic auth| web
end
subgraph core [Shared Python core]
tools["tools.py<br/>5 tool functions"]
llm["llm.py<br/>LiteLLM router"]
jc["jenkins_client.py<br/>httpx + crumb"]
end
repo -.git clone.-> local
repo -.git clone.-> shared
mcp --> tools
web --> llm
web --> tools
llm -->|"tool calls"| tools
tools --> jc
jc -->|REST + basic auth| jenkins[(Jenkins<br/>private network)]tools.py ist die einzige Quelle der Wahrheit. Sowohl der MCP-Server als auch der LiteLLM-Agent in der Web-App rufen dieselben fünf Funktionen auf, sodass das Verhalten zwischen Cursor und der Team-Chat-UI identisch ist.
Die fünf Tools:
Tool | Was es tut |
| Stellt die |
| Stellt die |
| Ergebnis, Dauer, Parameter des letzten oder eines spezifischen Builds |
| Verlauf (neueste zuerst) |
| Letzte N Zeilen der Konsolenausgabe |
Schnellstart - MCP in Cursor
Vollständige Anleitung: docs/CURSOR_MCP.md. Kurzfassung:
Generieren Sie ein Jenkins-API-Token unter
<JENKINS_URL>/me/configure-> Add new Token.Installieren Sie
uv:pipx install uvBearbeiten Sie
~/.cursor/mcp.json(Windows:%USERPROFILE%\.cursor\mcp.json):{ "mcpServers": { "netlinq-jenkins": { "command": "uvx", "args": [ "--from", "git+ssh://git@github.com/<your-org>/netlinq-jenkins-mcp.git@main", "netlinq-jenkins-mcp" ], "env": { "JENKINS_URL": "https://jenkins.internal.example.com", "JENKINS_USER": "your-user", "JENKINS_TOKEN": "your-api-token" } } } }Starten Sie Cursor neu. Achten Sie auf den grünen Punkt neben netlinq-jenkins in Einstellungen -> MCP.
Versuchen Sie im Chat: "build 7.0 release package". Der Agent wird dies bestätigen, bevor er Jenkins tatsächlich auslöst.
Schnellstart - Team-Chat-UI (Docker)
git clone git@github.com:<your-org>/netlinq-jenkins-mcp.git
cd netlinq-jenkins-mcp
cp .env.example .env
# edit .env: JENKINS_*, LLM_*, WEB_USERS
# Create at least one web user. The hash MUST be bcrypt-hashed.
python -c "from passlib.hash import bcrypt; print('alice:' + bcrypt.hash('secret123'))"
# paste the line into WEB_USERS=
docker compose up -d --build
# browse http://<host>:8000 - log in with alice / secret123Was das Team sieht:
Chateingabe unten, Gesprächsverlauf in der Mitte.
Live-Panels für "kürzliche Builds" für beide Pipelines auf der rechten Seite, alle 5 Sekunden aktualisiert.
Tool-Call-Karten erweitern sich inline, sodass jeder genau sehen kann, was der Bot tut.
Ein "Reset"-Button im Header löscht das Gedächtnis des Agenten.
Lokale Entwicklung (ohne Docker)
# Python side
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # PowerShell
# or: source .venv/bin/activate # bash
pip install -e ".[dev]"
# Frontend side (only needed for the web mode)
cd ui
npm install
npm run build # writes ui/dist/, which web.py auto-serves
cd ..
# Run the web app
netlinq-jenkins-web
# or, with auto-reload:
uvicorn netlinq_jenkins.web:create_app --factory --reload --port 8000
# Or run as MCP (stdio - the way Cursor will spawn it)
netlinq-jenkins-mcp
# Run tests
pytestKonfigurationsreferenz
Alle Einstellungen stammen aus Umgebungsvariablen (oder einer .env-Datei).
Siehe .env.example für die kanonische Liste.
Variable | Standard | Zweck |
| erforderlich | Basis-URL des Jenkins-Controllers |
| erforderlich | Benutzername des Dienstkontos |
| erforderlich | API-Token (bevorzugt) oder Passwort |
| leer | Pfad zu einem CA-Bundle für selbstsignierte TLS-Zertifikate, oder |
|
| Überschreiben, falls Ihr Job anders heißt |
|
| Name des Versionsparameters des Jobs |
|
| Name der Patch-Pipeline |
|
| Name des Repo-Parameters der Patch-Pipeline |
|
| Name des Tag-Parameters der Patch-Pipeline |
|
| Informativ - LiteLLM wählt basierend auf |
|
| |
| - | Anbieter-Schlüssel (nur Web-Modus) |
| - | Für Azure / Ollama / selbstgehostete Endpunkte |
|
| FastAPI-Bind-Host |
|
| FastAPI-Bind-Port |
| leer |
|
| - | Optionaler |
|
| JSONL-Datei, an die jeder Tool-Aufruf angehängt wird |
Jenkins-Parameternamen entdecken
Wenn VERSION / REPO / TAG nicht Ihre tatsächlichen Parameternamen sind, fragen Sie Jenkins:
curl -s -u "$JENKINS_USER:$JENKINS_TOKEN" \
"$JENKINS_URL/job/NetLinQ%20EMS%20Release%20pipeline/api/json?tree=property[parameterDefinitions[name,type,defaultParameterValue[value]]]" \
| jqÜberschreiben Sie dann die entsprechende *_PARAM-Umgebungsvariable in .env oder in Ihrer Cursor mcp.json.
Tipps für LLM-Anbieter
Der Web-Modus verwendet LiteLLM, sodass Sie Anbieter rein über Umgebungsvariablen wechseln können. Häufige Kombinationen:
Anbieter |
|
|
|
OpenAI |
|
| - |
Anthropic |
|
| - |
Azure OpenAI |
| Azure-Schlüssel |
|
Ollama (lokal) |
| - |
|
OpenAI-kompatibel |
| Schlüssel |
|
Der MCP-in-Cursor-Modus benötigt nichts davon - Cursors eigenes Modell steuert das Gespräch und ruft einfach unsere Tools auf.
Sicherheitshinweise
.envwird von Git ignoriert - Geheimnisse verlassen niemals den Host.Der Web-Modus erfordert HTTP-Basic-Auth (bcrypt-gehasht in
WEB_USERS).Ein optionales
WEB_API_SHARED_SECRETfügt einen header-basierten zweiten Faktor für/api/*hinzu, gedacht für Deployments "hinter einem Reverse Proxy".Es ist kein eingehender Internetverkehr erforderlich - die App erreicht nur Jenkins.
API-Token werden gegenüber Passwörtern bevorzugt: Token umgehen den CSRF-Crumb-Prozess und sind einfacher zu widerrufen.
Eingaben werden vor jedem HTTP-Aufruf mit strengen Regexes (
version,repo,tag) validiert, sodass ein gesprächiges LLM keine Shell-Metazeichen einschleusen kann.Jeder Tool-Aufruf wird an das Audit-Log angehängt (siehe unten).
Audit-Log
Jeder erfolgreiche Trigger schreibt eine JSONL-Zeile in ${AUDIT_LOG_PATH}:
{"ts": "2026-05-06T20:30:11+00:00", "event": "trigger",
"pipeline": "NetLinQ EMS Release pipeline",
"parameters": {"VERSION": "7.0"},
"queue_url": "https://jenkins.internal.example.com/queue/item/812/"}Im Docker-Modus ist die Datei auf dem Host unter ./logs/audit.jsonl eingebunden.
Projektstruktur
netlinq-jenkins-mcp/
├── src/netlinq_jenkins/
│ ├── config.py # pydantic-settings
│ ├── jenkins_client.py # async httpx wrapper, crumb handling
│ ├── tools.py # 5 tool functions, used by both modes
│ ├── llm.py # LiteLLM tool-calling agent (web mode only)
│ ├── mcp_server.py # FastMCP stdio entrypoint (Cursor)
│ └── web.py # FastAPI app + serves the bundled UI
├── ui/ # Vite + React + Tailwind chat UI
│ ├── src/App.tsx # main chat layout
│ └── src/components/ # ToolCard, BuildsPanel
├── tests/ # pytest + pytest-httpx
├── docs/CURSOR_MCP.md # detailed Cursor integration guide
├── examples/cursor-mcp.json
├── Dockerfile # multi-stage: builds UI, then Python wheel
├── docker-compose.yml
├── .env.example
└── pyproject.tomlRoadmap / nächste Schritte
[ ] OIDC / SSO anstelle von HTTP-Basic für die Web-UI.
[ ] Slack-Bot-Adapter, der
/build 7.0-Slash-Befehle an dieselben Tools weiterleitet.[ ] Optionaler Read-Only-Modus (
READ_ONLY=true), der die Trigger-Tools deaktiviert.[ ] WebSocket-Log-Tail in der UI anstelle der abfragenden Seitenleiste.
[ ] Benutzerbezogenes Audit-Log anstelle einer globalen Datei.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Deploy & release tracking with native MCP — ask Claude what's in production and cut the release.
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
Remote MCP for Kiro release readiness, evidence binders, signoff, and CI approval receipts.
Draft, publish, schedule and analyze ReleasePad changelog posts from any MCP client.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables managing Jenkins operations like listing jobs, triggering builds, and checking build statuses through a configurable MCP server.310Apache 2.0
- AlicenseBqualityCmaintenanceA server that enables interaction with Jenkins CI/CD pipelines from any compatible MCP client (like Claude Desktop), allowing users to manage jobs, builds, coverage reports, and other Jenkins functionality through natural language.11500 npmMIT
- AlicenseBqualityDmaintenanceEnables comprehensive Jenkins automation through MCP interface, allowing users to manage builds, jobs, artifacts, and queues with natural language commands. Supports build triggering, monitoring, artifact retrieval, and system status checks with automatic CSRF protection and authentication.14190 npmMIT
- FlicenseAqualityDmaintenanceExposes a Jenkins controller's REST API to MCP-compatible clients, enabling job management, build triggering, and log retrieval through natural language.114-