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

docker-compose.yml — defines the mcp-atlassian container (image ghcr.io/sooperset/mcp-atlassian:latest, port 9000)
.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 up -d          # start the server
docker compose down           # stop the server
docker compose logs -f        # tail logs
docker compose pull && docker compose 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

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.

2.4 KiB Raw Blame History