PM Backlog — MCP Atlassian Setup

This project connects Claude Code to Jira via the mcp-atlassian MCP server, running as a Docker container over streamable HTTP.

Architecture

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

The server uses the streamable-http transport (not stdio), which keeps the MCP server as a persistent process independent of Claude Code sessions.

Prerequisites

• Docker and Docker Compose installed
• A Jira Cloud account with an API token (generate one here)

Configuration

Environment variables (.env)

Variable	Description
JIRA_URL	Your Jira Cloud base URL (e.g. https://your-org.atlassian.net)
JIRA_USERNAME	Your Atlassian account email
JIRA_API_TOKEN	Your Atlassian API token

OAuth2 variables are present but commented out — see the OAuth2 section below.

Claude Code (.mcp.json)

Claude Code is configured to connect to the MCP server via:

{
  "mcpServers": {
    "mcp-atlassian": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

This file is picked up automatically when Claude Code is opened in this directory.

Running the server

Start:

docker compose up -d

Stop:

docker compose down

View logs:

docker compose logs -f

Update to the latest image:

docker compose pull && docker compose up -d

The server listens on http://localhost:9000/mcp.

OAuth2 (future)

The mcp-atlassian server has built-in OAuth2 proxy support. When you are ready to enable it:

1. Uncomment the ATLASSIAN_OAUTH_* variables in .env and fill in your OAuth2 app credentials (created in the Atlassian developer console).
2. The server will expose standard OAuth2 discovery and token endpoints:
   • GET /.well-known/oauth-authorization-server
   • POST /oauth/token
   • POST /oauth/register
3. Place a reverse proxy (nginx, Caddy, etc.) in front of port 9000 to enforce bearer token validation before forwarding requests to /mcp.

Clients then authenticate with:

Authorization: Bearer <user_oauth_access_token>

For multi-tenant deployments, per-user Jira identity can be passed via:

X-Atlassian-Cloud-Id: <user_cloud_id>