PM Backlog — Jira MCP Server

This project runs the mcp-atlassian MCP server as a Docker container, connecting Claude Code to Jira Cloud.

Architecture

Claude Code  →  HTTP (localhost:9000/mcp)  →  Docker (mcp-atlassian)  →  Jira Cloud

Transport: streamable-http (persistent process, independent of Claude Code sessions).

Key files

compose/docker-compose.yml — defines the mcp-atlassian container (image ghcr.io/sooperset/mcp-atlassian:latest, port 9000)
k8s/ — Kubernetes manifests (namespace mcp, secret, deployment, service)
.env — Jira credentials (JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN); never commit this file
.mcp.json — tells Claude Code to connect to http://localhost:9000/mcp; auto-loaded when Claude Code opens this directory

Common commands

docker compose -f compose/docker-compose.yml up -d          # start the server
docker compose -f compose/docker-compose.yml down           # stop the server
docker compose -f compose/docker-compose.yml logs -f        # tail logs
docker compose -f compose/docker-compose.yml pull && docker compose -f compose/docker-compose.yml up -d  # update to latest image

Credentials

Credentials live in .env (already in .gitignore). Required variables:

Variable	Description
`JIRA_URL`	Jira Cloud base URL, e.g. `https://your-org.atlassian.net`
`JIRA_USERNAME`	Atlassian account email
`JIRA_API_TOKEN`	Atlassian API token — generate at id.atlassian.com

Kubernetes deployment

# 1. Create the secret from .env
kubectl create secret generic mcp-jira-credentials -n mcp \
  --from-literal=JIRA_URL="$(grep JIRA_URL .env | cut -d= -f2-)" \
  --from-literal=JIRA_USERNAME="$(grep JIRA_USERNAME .env | cut -d= -f2-)" \
  --from-literal=JIRA_API_TOKEN="$(grep JIRA_API_TOKEN .env | cut -d= -f2-)" \
  --dry-run=client -o yaml | kubectl apply -f -

# 2. Apply all manifests
kubectl apply -f k8s/

# 3. Access locally via port-forward
kubectl port-forward -n mcp svc/mcp-jira 9000:9000

MCP tools

Once the server is running and Claude Code is connected, Jira tools are available directly in this session (search issues, create/update tickets, etc.). The MCP server exposes the full mcp-atlassian tool surface.

Coding Guidelines

Language: all code, comments, commit messages, and documentation in English.
Comments: only when the why is non-obvious. No block comments, no section dividers.
Conciseness: no boilerplate, no placeholders, no "coming soon" stubs.
No over-engineering: solve the problem at hand; don't design for hypothetical futures.
Images: always use latest when the tag exists; pin to the latest known version only when latest is not published (e.g. Harbor). Keeps images up to date with security patches.

OAuth2 (future)

The image has built-in OAuth2 proxy support. To enable it:

Uncomment ATLASSIAN_OAUTH_* variables in .env and fill in credentials from the Atlassian developer console.
Put a reverse proxy (nginx/Caddy) in front of port 9000 to enforce bearer token validation before forwarding to /mcp.

3.2 KiB Raw Blame History