Atlassian MCP Server

Atlassian MCP Server

Search Jira and Confluence directly from your IDE — no browser needed.

Status: 416 tests passing | Hexagonal Architecture (DDD) | Jira v3 + Confluence v2

What Does This Do?

Talk to your AI assistant and get Atlassian data:

You: "What tickets are assigned to me?"
AI:  Shows your Jira tickets

You: "Find our deployment documentation"
AI:  Shows Confluence pages about deployment

Works with Cursor, Claude Code, or any MCP-compatible client.

Quick Start

1. Get Atlassian OAuth Credentials

1. Go to https://developer.atlassian.com/console/myapps/
2. Click Create > OAuth 2.0 integration
3. Name it: MCP Server
4. Callback URL: http://localhost:8084/auth/callback
5. Add permissions:
   • Jira: read:jira-work, read:jira-user
   • Confluence: read:confluence-content.all, search:confluence, read:confluence-space.summary
6. Copy your Client ID and Client Secret

2. Configure

cp env.example .env

Edit .env:

ATLASSIAN_SITE=yourcompany.atlassian.net   # no https://
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret

# Generate these:
TOKEN_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
REDIS_PASSWORD=$(node -e "console.log(require('crypto').randomBytes(16).toString('hex'))")

3. Start

docker-compose up -d

4. Authenticate

open http://localhost:8084/auth/login

Click "Accept" when Atlassian asks for permission.

5. Connect Your IDE

Cursor — edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "url": "http://localhost:8084/mcp",
      "type": "http"
    }
  }
}

Claude Code — edit ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "atlassian": {
      "url": "http://localhost:8084/mcp"
    }
  }
}

Restart your IDE after adding the config.

6. Test It

• "What Jira tickets are assigned to me?"
• "Find deployment documentation in Confluence"
• "Show me ticket ENG-123"

Available Tools

Architecture

                              MCP Protocol (HTTP)
  IDE / AI Client ──────────── http://localhost:8084/mcp
                                        │
  ┌─────────────────────────────────────┼─────────────────────────────┐
  │  Atlassian MCP Server               │                             │
  │                                     │                             │
  │  ┌──────────────┐   ┌───────────────┼────────────┐                │
  │  │ Domain       │   │ Application   │            │                │
  │  │              │   │               ▼            │                │
  │  │ Models       │◄──│ Use Cases (5)              │                │
  │  │ Services     │   │ Ports (interfaces)         │                │
  │  │ Value Objects│   │ DTOs (Zod validated)       │                │
  │  └──────────────┘   └──────────────┬─────────────┘                │
  │                                    │                              │
  │  ┌─────────────────────────────────┼────────────────────────────┐ │
  │  │ Infrastructure                  │                            │ │
  │  │                                 ▼                            │ │
  │  │ Adapters:  JiraRestAdapter, ConfluenceRestAdapter            │ │
  │  │ Auth:      OAuthAdapter, RedisTokenAdapter                   │ │
  │  │ Cache:     RedisCacheAdapter                                 │ │
  │  │ MCP:       McpToolRouter, toolDefinitions                    │ │
  │  │ Server:    Express routes, middleware                        │ │
  │  └──────┬──────────────┬───────────────────┬────────────────────┘ │
  └─────────┼──────────────┼───────────────────┼──────────────────────┘
            │              │                   │
   ┌────────▼────────┐ ┌──▼────────────┐ ┌────▼──────┐
   │ Jira REST API   │ │ Confluence    │ │ Redis     │
   │ v3 (search/JQL) │ │ v1 (search)   │ │ Cache +   │
   │                 │ │ v2 (pages)    │ │ Tokens    │
   └─────────────────┘ └───────────────┘ └───────────┘

Key design decisions:

• Hexagonal / DDD — Domain has zero infrastructure imports. Application layer defines port interfaces. Infrastructure implements adapters.
• Strangler Fig migration — Confluence v1 /content/{id} migrated to v2 /pages/{id}. v1 search (/content/search) stays (not deprecated).
• ESLint enforced layer boundaries — import-x/no-restricted-paths prevents domain from importing infrastructure.
• Composition Root — All wiring i