MCP Jira

Model Context Protocol (MCP) server for Jira. This integration supports both Jira Cloud and Server/Data Center deployments.

Example Usage

Ask your AI assistant to:

• 📝 Automatic Jira Updates - "Update Jira from our meeting notes"

• 🐛 Smart Jira Issue Filtering - "Show me urgent bugs in PROJ project from last week"

• 🔍 AI-Powered Jira Search - "Find all issues assigned to me that are due this week"

Feature Demo

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

Compatibility

Quick Start Guide

🔐 1. Authentication Setup

MCP Atlassian Jira supports three authentication methods:

A. API Token Authentication (Cloud) - Recommended

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens

2. Click Create API token, name it

3. Copy the token immediately

B. Personal Access Token (Server/Data Center)

1. Go to your profile (avatar) → Profile → Personal Access Tokens

2. Click Create token, name it, set expiry

3. Copy the token immediately

C. OAuth 2.0 Authentication (Cloud) - Advanced

1. Go to Atlassian Developer Console

2. Create an "OAuth 2.0 (3LO) integration" app

3. Configure Permissions (scopes) for Jira

4. Set Callback URL (e.g., http://localhost:8080/callback)

5. Run setup wizard:

   docker run --rm -i \ -p 8080:8080 \ -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \ ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

6. Follow prompts for Client ID, Secret, URI, and Scope

7. Complete browser authorization

8. Add obtained credentials to .env or IDE config:

   • ATLASSIAN_OAUTH_CLOUD_ID (from wizard)

   • ATLASSIAN_OAUTH_CLIENT_ID

   • ATLASSIAN_OAUTH_CLIENT_SECRET

   • ATLASSIAN_OAUTH_REDIRECT_URI

   • ATLASSIAN_OAUTH_SCOPE

If you are running mcp-atlassian part of a larger system that manages Atlassian OAuth 2.0 access tokens externally (e.g., through a central identity provider or another application), you can provide an access token directly to this MCP server. This method bypasses the interactive setup wizard and the server's internal token management (including refresh capabilities).

Requirements:

• A valid Atlassian OAuth 2.0 Access Token with the necessary scopes for the intended operations.

• The corresponding ATLASSIAN_OAUTH_CLOUD_ID for your Atlassian instance.

Configuration: To use this method, set the following environment variables (or use the corresponding command-line flags when starting the server):

• ATLASSIAN_OAUTH_CLOUD_ID: Your Atlassian Cloud ID. (CLI: --oauth-cloud-id)

• ATLASSIAN_OAUTH_ACCESS_TOKEN: Your pre-existing OAuth 2.0 access token. (CLI: --oauth-access-token)

Important Considerations for BYOT:

• Token Lifecycle Management: When using BYOT, the MCP server does not handle token refresh. The responsibility for obtaining, refreshing (before expiry), and revoking the access token lies entirely with you or the external system providing the token.

• Unused Variables: The standard OAuth client variables (ATLASSIAN_OAUTH_CLIENT_ID, ATLASSIAN_OAUTH_CLIENT_SECRET, ATLASSIAN_OAUTH_REDIRECT_URI, ATLASSIAN_OAUTH_SCOPE) are not used and can be omitted when configuring for BYOT.

• No Setup Wizard: The --oauth-setup wizard is not applicable and should not be used for this approach.

• No Token Cache Volume: The Docker volume mount for token storage (e.g., -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian") is also not necessary if you are exclusively using the BYOT method, as no tokens are stored or managed by this server.

• Scope: The provided access token must already have the necessary permissions (scopes) for the Jira operations you intend to perform.

This option is useful in scenarios where OAuth credential management is centralized or handled by other infrastructure components.

📦 2. Installation

MCP Atlassian Jira is distributed as a Docker image. This is the recommended way to run the server, especially for IDE integration. Ensure you have Docker installed.

🛠️ IDE Integration

MCP Atlassian Jira is designed to be used with AI assistants through IDE integration.

⚙️ Configuration Methods

There are two main approaches to configure the Docker container:

1. Passing Variables Directly (shown in examples below)

2. Using an Environment File with --env-file flag (shown in collapsible sections)

📝 Configuration Examples

Method 1 (Passing Variables Directly):

For Server/Data Center deployments, use direct variable passing:

These examples show how to configure mcp-atlassian in your IDE (like Cursor or Claude Desktop) when using OAuth 2.0 for Atlassian Cloud.

Example for Standard OAuth 2.0 Flow (using Setup Wizard):

This configuration is for when you use the server's built-in OAuth client and have completed the OAuth setup wizard.

Example for Pre-existing Access Token (BYOT - Bring Your Own Token):

This configuration is for when you are providing your own externally managed OAuth 2.0 access token.

MCP Atlassian Jira supports routing API requests through standard HTTP/HTTPS/SOCKS proxies. Configure using environment variables:

• Supports standard HTTP_PROXY, HTTPS_PROXY, NO_PROXY, SOCKS_PROXY.

• Service-specific overrides are available (e.g., JIRA_HTTPS_PROXY, JIRA_NO_PROXY).

• Service-specific variables override global ones for that service.

Add the relevant proxy variables to the args (using -e) and env sections of your MCP configuration:

Credentials in proxy URLs are masked in logs. If you set NO_PROXY, it will be respected for requests to matching hosts.

MCP Atlassian Jira supports adding custom HTTP headers to all API requests. This feature is particularly useful in corporate environments where additional headers are required for security, authentication, or routing purposes.

Custom headers are configured using environment variables with comma-separated key=value pairs:

Security Considerations:

• Custom header values are masked in debug logs to protect sensitive information

• Ensure custom headers don't conflict with standard HTTP or Atlassian API headers

• Avoid including sensitive authentication tokens in custom headers if already using basic auth or OAuth

• Headers are sent with every API request - verify they don't interfere with API functionality

MCP Atlassian Jira supports multi-cloud OAuth scenarios where each user connects to their own Atlassian cloud instance. This is useful for multi-tenant applications, chatbots, or services where users provide their own OAuth tokens.

Minimal OAuth Configuration:

1. Enable minimal OAuth mode (no client credentials required):

   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000

2. Users provide authentication via HTTP headers:

   • Authorization: Bearer <user_oauth_token>

   • X-Atlassian-Cloud-Id: <user_cloud_id>

Example Integration (Python):

Configuration Notes:

• Each request can use a different cloud instance via the X-Atlassian-Cloud-Id header

• User tokens are isolated per request - no cross-tenant data leakage

• Falls back to global ATLASSIAN_OAUTH_CLOUD_ID if header not provided

• Compatible with standard OAuth 2.0 bearer token authentication

👥 HTTP Transport Configuration

Instead of using stdio, you can run the server as a persistent HTTP service using either:

• sse (Server-Sent Events) transport at /sse endpoint

• streamable-http transport at /mcp endpoint

Both transport types support single-user and multi-user authentication:

Authentication Options:

• Single-User: Use server-level authentication configured via environment variables

• Multi-User: Each user provides their own authentication:

  • Cloud: OAuth 2.0 Bearer tokens

  • Server/Data Center: Personal Access Tokens (PATs)

1. Start the server with your chosen transport:

   # For SSE transport docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport sse --port 9000 -vv # OR for streamable-http transport docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000 -vv

2. Configure your IDE (single-user example):

   SSE Transport Example:

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

   Streamable-HTTP Transport Example:

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

Here's a complete example of setting up multi-user authentication with streamable-HTTP transport:

1. First, run the OAuth setup wizard to configure the server's OAuth credentials:

   docker run --rm -i \ -p 8080:8080 \ -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \ ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

2. Start the server with streamable-HTTP transport:

   docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000 -vv

3. Configure your IDE's MCP settings:

Choose the appropriate Authorization method for your Atlassian deployment:

• Cloud (OAuth 2.0): Use this if your organization is on Atlassian Cloud and you have an OAuth access token for each user.

• Server/Data Center (PAT): Use this if you are on Atlassian Server or Data Center and each user has a Personal Access Token (PAT).

Cloud (OAuth 2.0) Example:

Server/Data Center (PAT) Example:

4. Required environment variables in .env:

   JIRA_URL=https://your-company.atlassian.net ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work offline_access ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

Tools

Key Jira Tools

• jira_get_issue: Get details of a specific issue

• jira_search: Search issues using JQL

• jira_create_issue: Create a new issue

• jira_update_issue: Update an existing issue

• jira_transition_issue: Transition an issue to a new status

• jira_add_comment: Add a comment to an issue

*Tool only available on Jira Cloud

Tool Filtering and Access Control

The server provides two ways to control tool access:

1. Tool Filtering: Use --enabled-tools flag or ENABLED_TOOLS environment variable to specify which tools should be available:

   # Via environment variable ENABLED_TOOLS="jira_get_issue,jira_search" # Or via command line flag docker run ... --enabled-tools "jira_get_issue,jira_search" ...

2. Read/Write Control: Tools are categorized as read or write operations. When READ_ONLY_MODE is enabled, only read operations are available regardless of ENABLED_TOOLS setting.

Troubleshooting & Debugging

Common Issues

• Authentication Failures:

  • For Cloud: Check your API tokens (not your account password)

  • For Server/Data Center: Verify your personal access token is valid and not expired

• SSL Certificate Issues: If using Server/Data Center and encounter SSL errors, set JIRA_SSL_VERIFY=false

• Permission Errors: Ensure your Atlassian account has sufficient permissions to access the projects

• Custom Headers Issues: See the "Debugging Custom Headers" section below to analyze and resolve issues with custom headers

Debugging Custom Headers

To verify custom headers are being applied correctly:

1. Enable Debug Logging: Set MCP_VERY_VERBOSE=true to see detailed request logs

   # In your .env file or environment MCP_VERY_VERBOSE=true MCP_LOGGING_STDOUT=true

2. Check Header Parsing: Custom headers appear in logs with masked values for security:

   DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}

3. Verify Service-Specific Headers: Check logs to confirm the right headers are being used:

   DEBUG Jira request headers: service-specific headers applied

4. Test Header Format: Ensure your header string format is correct:

   # Correct format JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2 # Incorrect formats (will be ignored) JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2" # Extra quotes JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2 # Colon instead of equals JIRA_CUSTOM_HEADERS=X-Custom = value1 # Spaces around equals

Security Note: Header values containing sensitive information (tokens, passwords) are automatically masked in logs to prevent accidental exposure.

Debugging Tools

Security

• Never share API tokens

• Keep .env files secure and private

• See SECURITY.md for best practices

Contributing

We welcome contributions to MCP Atlassian Jira! If you'd like to contribute:

1. Check out our CONTRIBUTING.md guide for detailed development setup instructions.

2. Make changes and submit a pull request.

We use pre-commit hooks for code quality and follow semantic versioning for releases.

License

Licensed under MIT - see LICENSE file. This is not an official Atlassian product.