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:

Uncomment the ATLASSIAN_OAUTH_* variables in .env and fill in your OAuth2 app credentials (created in the Atlassian developer console).
The server will expose standard OAuth2 discovery and token endpoints:
- GET /.well-known/oauth-authorization-server
- POST /oauth/token
- POST /oauth/register
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>

2.4 KiB Raw Permalink Blame History