How sooperset/mcp-atlassian works
Purpose and Entry Points
MCP Atlassian is a Python Model Context Protocol server that exposes Jira and Confluence operations as AI-agent tools. It supports Atlassian Cloud and Server/Data Center. The package/server entry point is centered on src/mcp_atlassian/servers/main.py; service-specific MCP registrations live in src/mcp_atlassian/servers/jira.py and src/mcp_atlassian/servers/confluence.py.
MCP Server and Transport Layer
The server accepts MCP clients such as IDE agents over stdio and documented HTTP transports, then selects/configures lifecycle behavior, dependencies, error handling, and request context. This is the principal boundary between untrusted MCP requests and Atlassian operations.
• src/mcp_atlassian/servers/main.py
• src/mcp_atlassian/servers/context.py
• src/mcp_atlassian/servers/error_handling.py
OAuth-capable HTTP deployment includes a proxy layer and per-client storage rather than treating the process as only a single-user local stdio server.
• src/mcp_atlassian/servers/oauth_proxy.py
• src/mcp_atlassian/servers/client_storage.py
• docs/http-transport.mdx
Tool Registration, Policy, and Dispatch
Jira and Confluence server modules define the externally visible tool surface (98 tools). Toolsets and helpers organize registration and enforce tool-level selection/policy, while server dependency wiring obtains the appropriate configured clients. MCP tool calls are translated into domain-module calls and returned in MCP-compatible results.
• src/mcp_atlassian/servers/jira.py
• src/mcp_atlassian/servers/confluence.py
• src/mcp_atlassian/utils/toolsets.py
Jira Domain Adapter
The Jira adapter is organized by API capability: issues, search/JQL, projects, agile boards/sprints, transitions, comments, attachments, service management, forms, SLA, and metrics. It isolates Jira Cloud/Server API differences and request details behind a central client/configuration boundary.
• src/mcp_atlassian/jira/client.py
• src/mcp_atlassian/jira/issues.py
• src/mcp_atlassian/jira/search.py
Control flow is generally MCP tool → Jira domain operation → Jira client HTTP request → normalized model/result. Jira-specific preprocessing converts AI-friendly content into Jira formats before write operations.
• src/mcp_atlassian/preprocessing/jira.py
• src/mcp_atlassian/jira/formatting.py
Confluence Domain Adapter
The Confluence side similarly separates pages, search/CQL, spaces, comments, attachments, permissions/restrictions, templates, labels, users, and analytics. Its client handles deployment/API-version concerns, including a v2 adapter, so tool implementations need not directly encode transport variants.
• src/mcp_atlassian/confluence/client.py
• src/mcp_atlassian/confluence/pages.py
• src/mcp_atlassian/confluence/v2_adapter.py
Content preprocessing forms the write-path boundary between MCP text inputs and Confluence content representations.
• src/mcp_atlassian/preprocessing/confluence.py
• src/mcp_atlassian/confluence/search.py
Models and Shared Data Contracts
Typed/shared models represent Jira and Confluence API entities and normalize external payloads at the service boundary. They are the common contract used by domain operations, rather than exposing raw Atlassian JSON across the server layer.
• src/mcp_atlassian/models/base.py
• src/mcp_atlassian/models/jira/issue.py
• src/mcp_atlassian/models/confluence/page.py
Authentication, HTTP Security, and External Boundaries
External dependencies are Atlassian Jira and Confluence REST APIs, using Cloud API tokens, Server/Data Center personal access tokens, and OAuth 2.0 where configured. Shared utilities centralize credential/environment loading, OAuth setup/token validation, HTTP behavior, proxy support, SSL handling, pagination, and SSRF defenses.
• src/mcp_atlassian/utils/oauth.py
• src/mcp_atlassian/utils/http.py
• src/mcp_atlassian/utils/ssrf_adapter.py
Packaging and Deployment
The runtime is a Python package distributed for uvx/pip and containerized for production. Docker and Helm support running it as a networked MCP service, with Kubernetes deployment, service, ingress, secrets/config, RBAC, optional persistence, and autoscaling defined in the chart.
• pyproject.toml
• Dockerfile
• helm/templates/deployment.yaml
Main entry points: main.py Server entry point · issues.py Jira domain operations · pages.py Confluence domain operations · toolsets.py Tool policy & selection
Components 18
MCP Runtime
MCP request boundary, tool registration, and HTTP deployment support.
- MCP clients · IDE agents connect over stdio or HTTP.
- Server entry point · Configures lifecycle, dependencies, transport, and request context.
src/mcp_atlassian/servers/main.py - Request context & errors · Supplies request context and MCP-safe error handling.
src/mcp_atlassian/servers/context.py - Jira & Confluence tools · Registers the externally visible Jira and Confluence tools.
src/mcp_atlassian/servers/jira.py - Tool policy & selection · Organizes toolsets and applies tool-level selection policy.
src/mcp_atlassian/utils/toolsets.py - OAuth HTTP proxy · Supports OAuth-capable network deployment and per-client state.
src/mcp_atlassian/servers/oauth_proxy.py - Per-client storage · Stores state for HTTP/OAuth clients.
src/mcp_atlassian/servers/client_storage.py
Jira Adapter
Jira operations and API compatibility boundary.
- Jira domain operations · Issues, JQL search, projects, agile, service management, and write operations.
src/mcp_atlassian/jira/issues.py - Jira content formatting · Converts AI-friendly content into Jira representations.
src/mcp_atlassian/preprocessing/jira.py - Jira client · Centralizes Cloud and Server/Data Center request differences.
src/mcp_atlassian/jira/client.py
Confluence Adapter
Confluence operations and API compatibility boundary.
- Confluence domain operations · Pages, CQL search, spaces, content, permissions, and attachments.
src/mcp_atlassian/confluence/pages.py - Confluence content preprocessing · Transforms MCP text inputs into Confluence content representations.
src/mcp_atlassian/preprocessing/confluence.py - Confluence client & v2 adapter · Hides deployment, API-version, and v2 transport variants.
src/mcp_atlassian/confluence/client.py
Shared Contracts & Security
Normalized entities and shared external-access controls.
- Normalized models · Typed Jira and Confluence entities isolate server code from raw API payloads.
src/mcp_atlassian/models/base.py - Auth, HTTP & SSRF controls · Centralizes credentials, OAuth, HTTP behavior, SSL, pagination, and SSRF defenses.
src/mcp_atlassian/utils/oauth.py
Packaging & Deployment
Local package, container, and Kubernetes deployment artifacts.
- Python package & container · Distributed through pip/uvx and packaged for container runtime.
pyproject.toml - Helm Kubernetes deployment · Deploys networked MCP service with ingress, secrets, RBAC, persistence, and autoscaling options.
helm/templates/deployment.yaml
Other components
- Atlassian REST APIs · Jira and Confluence Cloud or Server/Data Center endpoints.
Connections 20
- MCP clients → Server entry point: stdio / HTTP requests
- Server entry point → Request context & errors: establishes context
- Server entry point → Jira & Confluence tools: loads tools
- Server entry point → OAuth HTTP proxy: network transport
- OAuth HTTP proxy → Per-client storage: client state
- Jira & Confluence tools → Tool policy & selection: selection policy
- Tool policy & selection → Jira domain operations: dispatches Jira calls
- Tool policy & selection → Confluence domain operations: dispatches Confluence calls
- Jira domain operations → Jira content formatting: formats writes
- Jira domain operations → Jira client: uses
- Confluence domain operations → Confluence content preprocessing: formats writes
- Confluence domain operations → Confluence client & v2 adapter: uses
- Jira domain operations → Normalized models: normalized results
- Confluence domain operations → Normalized models: normalized results
- Jira client → Auth, HTTP & SSRF controls: authenticated HTTP
- Confluence client & v2 adapter → Auth, HTTP & SSRF controls: authenticated HTTP
- Auth, HTTP & SSRF controls → Atlassian REST APIs: secured REST access
- Python package & container → Server entry point: packages runtime
- Helm Kubernetes deployment → Python package & container: deploys container
- Helm Kubernetes deployment → OAuth HTTP proxy: hosts HTTP service