The mcp-atlassian server integrates Atlassian products (Jira, Confluence, Bitbucket, and Xray for Jira) with AI assistants, enabling automated interactions across these platforms.
Jira: Search issues using JQL; get issue details, transitions, worklogs, and changelogs; create/update/delete issues (individually or in batch); add comments and log work; transition issues through workflows; manage sprints, agile boards, and versions; link issues; download/upload attachments; retrieve user profiles.
Confluence: Search content using CQL or plain text; get page content (with Markdown conversion), child pages, comments, and labels; create/update/delete pages; add comments and labels; search users.
Bitbucket: List workspaces, projects, repositories, branches, and pull requests; read file content and directory listings; view commit history and diffs; analyze PR review status; create pull requests and branches; add regular, inline, and blocker comments to pull requests.
Xray for Jira (Server/Data Center only): Retrieve tests, test runs, test executions, test plans, test sets, and test steps; create/update/delete test steps; update test run statuses and associate defects.
Additional features: Supports Cloud and Server/Data Center deployments; multiple authentication methods (API tokens, PAT, OAuth 2.0, dynamic headers); configurable read-only mode (globally or per-product); tool filtering; and multi-tenant support.
Provides integration with Atlassian products including Confluence, Jira, Bitbucket, and Xray for Jira. Supports both Cloud and Server/Data Center deployments. Enables AI agents to search Confluence, manage Jira issues, interact with Bitbucket repositories, and handle Xray test management.
Enables interacting with Bitbucket repositories. Supports Server/Data Center deployments (Cloud not tested).
Enables searching, reading, and creating Confluence pages. Supports Cloud and Server/Data Center deployments.
Enables creating, updating, and querying Jira issues. Supports Cloud and Server/Data Center deployments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-atlassian Find our OKR guide in Confluence and summarize it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for Atlassian products (Confluence, Jira, Bitbucket, and Xray for Jira). This integration supports Confluence, Jira, and Bitbucket for both Cloud and Server/Data Center deployments. Xray for Jira is available only on Server/Data Center deployments and always uses the Jira URL and credentials you configure. Note: This project is a fork from mcp-atlassian. The project at the time of making a fork has not been maintained for a while with couple of dozen pull requests and a few issues on the github project. Hence, it was about time to fork the project and make some fixes.
Ask your AI assistant to:
📝 Automatic Jira Updates - "Update Jira from our meeting notes"
🔍 AI-Powered Confluence Search - "Find our OKR guide in Confluence and summarize it"
🐛 Smart Jira Issue Filtering - "Show me urgent bugs in PROJ project from last week"
📄 Content Creation & Management - "Create a tech design doc for XYZ feature"
🧪 Test Management with Xray for Jira - "Get test execution results for the latest sprint"
📊 Quality Assurance Tracking - "Update test run status and add defects found during testing"
https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e
https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785
Product | Deployment Type | Support Status |
Confluence | Cloud | ✅ Fully supported |
Confluence | Server/Data Center | ✅ Supported (version 6.0+) |
Jira | Cloud | ✅ Fully supported |
Jira | Server/Data Center | ✅ Supported (version 8.14+) |
Bitbucket | Cloud | ⚠️ Not Tested |
Bitbucket | Server/Data Center | ✅ Supported (version 9.0+) |
Xray for Jira | Cloud | ❌ Not Supported |
Xray for Jira | Server/Data Center | ✅ Supported (Jira 8.0+) |
Related MCP server: MCP Atlassian
MCP Atlassian supports four authentication methods:
Go to https://id.atlassian.com/manage-profile/security/api-tokens
Click Create API token, name it
Copy the token immediately
Go to your profile (avatar) → Profile → Personal Access Tokens
Click Create token, name it, set expiry
Copy the token immediately
OAuth 2.0 is more complex to set up but provides enhanced security features. For most users, API Token authentication (Method A) is simpler and sufficient.
Create an "OAuth 2.0 (3LO) integration" app
Configure Permissions (scopes) for Jira/Confluence
Set Callback URL (e.g., http://localhost:8080/callback)
Run setup wizard:
docker run --rm -i \
-p 8080:8080 \
-v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
ghcr.io/SharkyND/mcp-atlassian:latest --oauth-setup -vFollow prompts for Client ID, Secret, URI, and Scope
Complete browser authorization
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
For the standard OAuth flow described above, includeoffline_access in your scope (e.g., read:jira-work write:jira-work offline_access). This allows the server to refresh the access token automatically.
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/Confluence operations you intend to perform.
This option is useful in scenarios where OAuth credential management is centralized or handled by other infrastructure components.
Header-based authentication enables dynamic, per-request credential management without requiring environment variables or server restarts. This is ideal for multi-tenant applications, serverless environments, or when credentials need to be managed dynamically.
With header-based authentication, you can pass Jira, Confluence, and Bitbucket credentials directly through HTTP headers on each request. Xray for Jira automatically reuses the Jira headers. This method supports both Personal Access Tokens (PAT) for Server/Data Center and API tokens for Cloud deployments.
Required Headers:
For Jira authentication:
X-Atlassian-Jira-Personal-Token: Your Jira PAT or API token
X-Atlassian-Jira-Url: Your Jira instance URL
For Confluence authentication:
X-Atlassian-Confluence-Personal-Token: Your Confluence PAT or API token
X-Atlassian-Confluence-Url: Your Confluence instance URL
For Bitbucket authentication:
X-Atlassian-Bitbucket-Personal-Token: Your Bitbucket PAT or app password
X-Atlassian-Bitbucket-Url: Your Bitbucket instance URL
For Xray for Jira authentication:
Reuses your Jira headers (X-Atlassian-Jira-Personal-Token and X-Atlassian-Jira-Url), which must point to a Server/Data Center Jira with Xray installed.
Xray for Jira tools are disabled by default. To enable Xray for Jira tools, set the X-Atlassian-Enable-Xray header to true.
Benefits:
✅ No environment variables required
✅ Per-request authentication
✅ Multi-tenant support
✅ Dynamic credential management
✅ Zero server configuration needed
✅ Works with both Cloud and Server/Data Center
Example MCP Client Configuration:
{
"Atlassian": {
"url": "http://localhost:8000/mcp",
"headers": {
"X-Atlassian-Jira-Personal-Token": "your_jira_pat_or_api_token",
"X-Atlassian-Jira-Url": "https://your-jira-instance.com",
"X-Atlassian-Confluence-Personal-Token": "your_confluence_pat_or_api_token",
"X-Atlassian-Confluence-Url": "https://your-confluence-instance.com",
"X-Atlassian-Bitbucket-Personal-Token": "your_bitbucket_pat_or_app_password",
"X-Atlassian-Bitbucket-Url": "https://your-bitbucket-instance.com",
"X-Atlassian-Read-Only-Mode": "true",
"X-Atlassian-Jira-Read-Only-Mode": "false"
},
"type": "http"
}
}Per-product headers override the globalX-Atlassian-Read-Only-Mode header for that product. In the example above the global flag enables read-only for Confluence and Bitbucket, while Jira remains in read/write mode.
Multi-Cloud OAuth Support: If you're building a multi-tenant application where users provide their own OAuth tokens, see the Multi-Cloud OAuth Support section for minimal configuration setup.
MCP Atlassian is distributed as a Docker image. This is the recommended way to run the server, especially for IDE integration. Ensure you have Docker installed.
# Pull Pre-built Image
docker pull ghcr.io/SharkyND/mcp-atlassian:latestMCP Atlassian is designed to be used with AI assistants through IDE integration.
For Claude Desktop: Locate and edit the configuration file directly:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
For Cursor: Open Settings → MCP → + Add new global MCP server
There are three main approaches to configure the Docker container:
Passing Variables Directly (shown in examples below)
Using an Environment File with --env-file flag (shown in collapsible sections)
Header-Based Authentication (no environment variables required - see Header-Based Authentication Configuration)
Common environment variables include:
CONFLUENCE_SPACES_FILTER: Filter by space keys (e.g., "DEV,TEAM,DOC")
JIRA_PROJECTS_FILTER: Filter by project keys (e.g., "PROJ,DEV,SUPPORT")
READ_ONLY_MODE: Set to true to disable write operations for all products
JIRA_READ_ONLY_MODE: Set to true to disable write operations for Jira only
CONFLUENCE_READ_ONLY_MODE: Set to true to disable write operations for Confluence only
BITBUCKET_READ_ONLY_MODE: Set to true to disable write operations for Bitbucket only
MCP_VERBOSE: Set to "true" for more detailed logging
MCP_LOGGING_STDOUT: Set to "true" to log to stdout instead of stderr
ENABLED_TOOLS: Comma-separated list of tool names to enable (e.g., "confluence_search,jira_get_issue")
Header-Based Authentication (no environment variables needed):
X-Atlassian-Jira-Personal-Token: Jira PAT/API token (passed as HTTP header), used for XRay as well
X-Atlassian-Jira-Url: Jira instance URL (passed as HTTP header), used for XRay as well
X-Atlassian-Confluence-Personal-Token: Confluence PAT/API token (passed as HTTP header)
X-Atlassian-Confluence-Url: Confluence instance URL (passed as HTTP header)
X-Atlassian-Bitbucket-Url: Bitbucket URL (passed as HTTP header)
X-Atlassian-Bitbucket-Personal-Token: Bitbucket PAT token (passed as HTTP header)
X-Atlassian-Read-Only-Mode: Global per-request read-only mode — applies to all products (passed as HTTP header)
X-Atlassian-Jira-Read-Only-Mode: Per-request read-only mode for Jira only (passed as HTTP header)
X-Atlassian-Confluence-Read-Only-Mode: Per-request read-only mode for Confluence only (passed as HTTP header)
X-Atlassian-Bitbucket-Read-Only-Mode: Per-request read-only mode for Bitbucket only (passed as HTTP header)
X-Atlassian-Enable-Xray: Enable/disable Xray for Jira tools (disabled by default)
See the .env.example file for all available options.
Method 1 (Passing Variables Directly):
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_USERNAME",
"-e", "CONFLUENCE_API_TOKEN",
"-e", "JIRA_URL",
"-e", "JIRA_USERNAME",
"-e", "JIRA_API_TOKEN",
"-e", "BITBUCKET_URL",
"-e", "BITBUCKET_USERNAME",
"-e", "BITBUCKET_APP_PASSWORD",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "your_confluence_api_token",
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_jira_api_token",
"BITBUCKET_URL": "https://bitbucket.org",
"BITBUCKET_USERNAME": "your.email@company.com",
"BITBUCKET_APP_PASSWORD": "your_bitbucket_app_password"
}
}
}
}{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--env-file",
"/path/to/your/mcp-atlassian.env",
"ghcr.io/SharkyND/mcp-atlassian:latest"
]
}
}
}For Server/Data Center deployments, use direct variable passing:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_PERSONAL_TOKEN",
"-e", "CONFLUENCE_SSL_VERIFY",
"-e", "JIRA_URL",
"-e", "JIRA_PERSONAL_TOKEN",
"-e", "JIRA_SSL_VERIFY",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"CONFLUENCE_URL": "https://confluence.your-company.com",
"CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
"CONFLUENCE_SSL_VERIFY": "false",
"JIRA_URL": "https://jira.your-company.com",
"JIRA_PERSONAL_TOKEN": "your_jira_pat",
"JIRA_SSL_VERIFY": "false"
}
}
}
}SetCONFLUENCE_SSL_VERIFY and JIRA_SSL_VERIFY to "false" only if you have self-signed certificates.
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.
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
"-e", "JIRA_URL",
"-e", "CONFLUENCE_URL",
"-e", "ATLASSIAN_OAUTH_CLIENT_ID",
"-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
"-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
"-e", "ATLASSIAN_OAUTH_SCOPE",
"-e", "ATLASSIAN_OAUTH_CLOUD_ID",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"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 read:confluence-content.all write:confluence-content offline_access",
"ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
}
}
}
}For the Standard Flow:
ATLASSIAN_OAUTH_CLOUD_ID is obtained from the --oauth-setup wizard output or is known for your instance.
Other ATLASSIAN_OAUTH_* client variables are from your OAuth app in the Atlassian Developer Console.
JIRA_URL and CONFLUENCE_URL for your Cloud instances are always required.
The volume mount (-v .../.mcp-atlassian:/home/app/.mcp-atlassian) is crucial for persisting the OAuth tokens obtained by the wizard, enabling automatic refresh.
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.
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "JIRA_URL",
"-e", "CONFLUENCE_URL",
"-e", "ATLASSIAN_OAUTH_CLOUD_ID",
"-e", "ATLASSIAN_OAUTH_ACCESS_TOKEN",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_KNOWN_CLOUD_ID",
"ATLASSIAN_OAUTH_ACCESS_TOKEN": "YOUR_PRE_EXISTING_OAUTH_ACCESS_TOKEN"
}
}
}
}For the BYOT Method:
You primarily need JIRA_URL, CONFLUENCE_URL, ATLASSIAN_OAUTH_CLOUD_ID, and ATLASSIAN_OAUTH_ACCESS_TOKEN.
Standard OAuth client variables (ATLASSIAN_OAUTH_CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, SCOPE) are not used.
Token lifecycle (e.g., refreshing the token before it expires and restarting mcp-atlassian) is your responsibility, as the server will not refresh BYOT tokens.
This configuration uses the new dynamic header-based authentication feature. No environment variables are required - credentials are passed through HTTP headers on each request.
Minimal Docker Configuration (No Environment Variables Needed):
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"ghcr.io/SharkyND/mcp-atlassian:latest"
]
}
}
}MCP Client Configuration with Headers:
Configure your MCP client to send authentication headers with each request:
{
"Atlassian": {
"url": "http://localhost:8000/mcp",
"headers": {
"X-Atlassian-Read-Only-Mode": "true",
"X-Atlassian-Jira-Read-Only-Mode": "false",
"X-Atlassian-Jira-Personal-Token": "your_jira_pat_or_api_token",
"X-Atlassian-Jira-Url": "https://your-jira-instance.com",
"X-Atlassian-Confluence-Personal-Token": "your_confluence_pat_or_api_token",
"X-Atlassian-Confluence-Url": "https://your-confluence-instance.com"
},
"type": "http"
}
}In the example above,X-Atlassian-Read-Only-Mode: true sets the global default (Confluence and Bitbucket become read-only), but X-Atlassian-Jira-Read-Only-Mode: false overrides that for Jira, keeping it in read/write mode.
Optional Docker Configuration with Read-Only Mode:
If you want to enable read-only mode globally (rather than per-request), you can still use environment variables:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "READ_ONLY_MODE",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"READ_ONLY_MODE": "true"
}
}
}
}Header-Based Authentication Benefits:
✅ Zero Configuration: No environment variables required
✅ Multi-Tenant Ready: Different credentials per request
✅ Dynamic: Credentials can change without server restart
✅ Flexible: Mix and match Jira/Confluence authentication
✅ Secure: Credentials are not stored in environment or files
Selective Service Authentication: You can authenticate with just Jira or just Confluence by providing only the relevant headers. The server will automatically detect available services based on the headers provided.
Service-specific overrides are available (e.g., JIRA_HTTPS_PROXY, CONFLUENCE_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:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "... existing Confluence/Jira vars",
"-e", "HTTP_PROXY",
"-e", "HTTPS_PROXY",
"-e", "NO_PROXY",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"... existing Confluence/Jira vars": "...",
"HTTP_PROXY": "http://proxy.internal:8080",
"HTTPS_PROXY": "http://proxy.internal:8080",
"NO_PROXY": "localhost,.your-company.com"
}
}
}
}Credentials in proxy URLs are masked in logs. If you set NO_PROXY, it will be respected for requests to matching hosts.
MCP Atlassian 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:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_USERNAME",
"-e", "CONFLUENCE_API_TOKEN",
"-e", "CONFLUENCE_CUSTOM_HEADERS",
"-e", "JIRA_URL",
"-e", "JIRA_USERNAME",
"-e", "JIRA_API_TOKEN",
"-e", "JIRA_CUSTOM_HEADERS",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "your_confluence_api_token",
"CONFLUENCE_CUSTOM_HEADERS": "X-Confluence-Service=mcp-integration,X-Custom-Auth=confluence-token,X-ALB-Token=secret-token",
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_jira_api_token",
"JIRA_CUSTOM_HEADERS": "X-Forwarded-User=service-account,X-Company-Service=mcp-atlassian,X-Jira-Client=mcp-integration"
}
}
}
}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 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:
Enable minimal OAuth mode (no client credentials required):
docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
ghcr.io/SharkyND/mcp-atlassian:latest \
--transport streamable-http --port 9000Users provide authentication via HTTP headers:
Authorization: Bearer <user_oauth_token>
X-Atlassian-Cloud-Id: <user_cloud_id>
Example Integration (Python):
import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
user_token = "user-specific-oauth-token"
user_cloud_id = "user-specific-cloud-id"
async def main():
# Connect to streamable HTTP server with custom headers
async with streamablehttp_client(
"http://localhost:9000/mcp",
headers={
"Authorization": f"Bearer {user_token}",
"X-Atlassian-Cloud-Id": user_cloud_id
}
) as (read_stream, write_stream, _):
# Create a session using the client streams
async with ClientSession(read_stream, write_stream) as session:
# Initialize the connection
await session.initialize()
# Example: Get a Jira issue
result = await session.call_tool(
"jira_get_issue",
{"issue_key": "PROJ-123"}
)
print(result)
asyncio.run(main())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
For Confluence Cloud only:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_USERNAME",
"-e", "CONFLUENCE_API_TOKEN",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "your_api_token"
}
}
}
}For Confluence Server/DC, use:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_PERSONAL_TOKEN",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"CONFLUENCE_URL": "https://confluence.your-company.com",
"CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
}
}
}
}For Jira Cloud only:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "JIRA_URL",
"-e", "JIRA_USERNAME",
"-e", "JIRA_API_TOKEN",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_api_token"
}
}
}
}For Jira Server/DC, use:
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "JIRA_URL",
"-e", "JIRA_PERSONAL_TOKEN",
"ghcr.io/SharkyND/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://jira.your-company.com",
"JIRA_PERSONAL_TOKEN": "your_personal_token"
}
}
}
}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)
Start the server with your chosen transport:
# For SSE transport
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/SharkyND/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/SharkyND/mcp-atlassian:latest \
--transport streamable-http --port 9000 -vvConfigure 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"
}
}
}By default the streamable-http transport keeps per-session state in memory, which requires sticky sessions when running more than one replica. Enable stateless mode so any request can be served by any instance behind a round-robin load balancer — ideal for multi-replica / autoscaled deployments.
Enable it with either the CLI flag or the environment variable:
Method | Value |
CLI flag |
|
Environment variable |
|
Applies to the streamable-http transport only (ignored for stdio).
The CLI flag takes precedence over the STATELESS_HTTP environment variable.
In stateless mode the server does not return an mcp-session-id header, so clients must not rely on session affinity.
# CLI flag
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/SharkyND/mcp-atlassian:latest \
--transport streamable-http --port 9000 --stateless-http -vv
# OR via environment variable
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
-e STATELESS_HTTP=true \
ghcr.io/SharkyND/mcp-atlassian:latest \
--transport streamable-http --port 9000 -vvHere's a complete example of setting up multi-user authentication with streamable-HTTP transport:
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/SharkyND/mcp-atlassian:latest --oauth-setup -vStart the server with streamable-HTTP transport:
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/SharkyND/mcp-atlassian:latest \
--transport streamable-http --port 9000 -vvConfigure 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:
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
}
}
}
}Server/Data Center (PAT) Example:
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
}
}
}
}Required environment variables in .env:
JIRA_URL=https://your-company.atlassian.net
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
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 read:confluence-content.all write:confluence-content offline_access
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizardThe server should have its own fallback authentication configured (e.g., via environment variables for API token, PAT, or its own OAuth setup using --oauth-setup). This is used if a request doesn't include user-specific authentication.
OAuth: Each user needs their own OAuth access token from your Atlassian OAuth app.
PAT: Each user provides their own Personal Access Token.
Multi-Cloud: For OAuth users, optionally include X-Atlassian-Cloud-Id header to specify which Atlassian cloud instance to use
The server will use the user's token for API calls when provided, falling back to server auth if not
User tokens should have appropriate scopes for their needed operations
Enforce username headers in requests by setting REQUIRE_USERNAME=true only for monitoring purpose. When the enviroment variable is passed in as true, it will be enable prometheus client to caputre username from the header and avalible to scrape through the service monitor:
# Environment variable
REQUIRE_USERNAME=true
# Helm chart
env:
REQUIRE_USERNAME: "true"When enabled, requests must include at least one username header:
X-Atlassian-Username
Returns 400 error if missing when enabled.
Prometheus Metrics available at /metrics endpoint:
Request counts, duration, errors by service
User activity tracking (when username headers provided)
Pod-specific metrics for Kubernetes deployments
Health Checks:
/healthz - Basic health status
/readyz - Kubernetes readiness probe
Kubernetes Integration:
Helm chart with monitoring configuration
Grafana dashboard provisioning via ConfigMaps
ServiceMonitor for Prometheus Operator
Read-only mode removes all tools tagged with write from tool discovery and blocks direct calls to write handlers. Unless configured, the server runs in read/write mode.
Read-only mode can be controlled globally (all products) or per-product (Jira, Confluence, Bitbucket independently). The effective state is recalculated on every request using this priority (highest first):
Priority | Scope | Mechanism |
1 | Per-product | HTTP header |
2 | Global | HTTP header |
3 | Per-product | Environment variable |
4 | Global | Environment variable |
5 | Per-product | CLI flag |
6 | Global | CLI flag |
Truthy values: true, 1, yes, on. Falsy values: false, 0, no, off. A falsy value at a higher priority overrides a truthy value at a lower priority.
When enabled for a product, its write tools are hidden in tools/list, and the @check_write_access decorator raises ValueError if a client tries to invoke one directly.
# All products read-only
uv run mcp-atlassian --transport streamable-http --port 8889 --read-only
# Per-product: only Jira is read-only
uv run mcp-atlassian --transport streamable-http --port 8889 --jira-read-only
# Combined: Jira and Confluence read-only, Bitbucket stays read/write
uv run mcp-atlassian --transport streamable-http --port 8889 --jira-read-only --confluence-read-only# Global — all products
set READ_ONLY_MODE=true # Windows CMD
$Env:READ_ONLY_MODE = "true" # PowerShell
export READ_ONLY_MODE=true # macOS/Linux
# Per-product overrides
$Env:JIRA_READ_ONLY_MODE = "true" # Jira only
$Env:CONFLUENCE_READ_ONLY_MODE = "true" # Confluence only
$Env:BITBUCKET_READ_ONLY_MODE = "true" # Bitbucket only
# Example: global read-only, but Jira stays read/write
$Env:READ_ONLY_MODE = "true"
$Env:JIRA_READ_ONLY_MODE = "false"Headers let you override the server defaults on a per-request basis without restarting.
{
"headers": {
"X-Atlassian-Read-Only-Mode": "true",
"X-Atlassian-Jira-Read-Only-Mode": "false",
"X-Atlassian-Confluence-Read-Only-Mode": "true",
"X-Atlassian-Bitbucket-Read-Only-Mode": "false"
}
}Header | Scope |
| All products (global fallback) |
| Jira only |
| Confluence only |
| Bitbucket only |
A per-product header always takes precedence over the global header for that product. In the example above, the global flag enables read-only for all products, but the Jira and Bitbucket headers override it back to read/write.
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
jira_summarize_attachments: Extract readable text from PDF/Office/CSV/JSON attachments (via Microsoft MarkItDown)
jira_get_attachment_images: Fetch image attachments as viewable image content so a vision-capable client model can describe them
confluence_search: Search Confluence content using CQL
confluence_get_page: Get content of a specific page
confluence_create_page: Create a new page
confluence_update_page: Update an existing page
list_workspaces_or_projects: List all accessible workspaces/projects
list_repositories: List repositories in a workspace or all accessible repositories
get_repository_info: Get detailed information about a specific repository
list_branches: List all branches in a repository
get_default_branch: Get the default branch of a repository
get_file_content: Get content of a specific file from a repository
list_directory: List contents of a directory in a repository
list_pull_requests: List pull requests for a repository
pull_request_activities: Get activities/comments for a pull request
get_pull_request: Get detailed information about a specific pull request
get_commit_changes: Get changes made in a specific commit
get_commits: Get commit history for a repository
create_pull_request: Create a new pull request
create_branch: Create a new branch in a repository
add_pull_request_blocker_comment: Add a blocking comment to a pull request
add_pull_request_comment: Add a regular comment to a pull request
add_pull_request_inline_comment: Add an inline comment on a specific line of a file in a pull request
get_tests: Retrieve information about specific tests
get_test_statuses: Get all available test statuses
get_test_runs: Get test runs for a specific test
get_test_runs_in_context: Get test runs from a Test Execution,
optionally including selected Test issue custom fields
get_test_run: Get an individual run with its execution metadata and steps
get_test_executions: Get test executions for a test
get_test_plans: Get test plans associated with a test
create_test_step: Create a new test step for a test
update_test_step: Update an existing test step
update_test_run_status: Update the status of a test run
update_test_run_defects: Associate defects with a test run
Operation | Jira Tools | Confluence Tools | Bitbucket Tools | Xray Tools |
Read |
|
|
|
|
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
|
| ||
|
| |||
|
| |||
|
| |||
|
| |||
| ||||
| ||||
|
| |||
|
| |||
| ||||
| ||||
| ||||
| ||||
Write |
|
|
|
|
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
| |||
|
| |||
|
| |||
|
| |||
|
| |||
|
| |||
|
| |||
|
| |||
|
| |||
| ||||
| ||||
|
*Tool only available on Jira Cloud
The server provides two ways to control tool access:
Tool Filtering: Use --enabled-tools flag or ENABLED_TOOLS environment variable to specify which tools should be available:
# Via environment variable
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
# Or via command line flag
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...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.
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
For older Confluence servers: Some older versions require basic authentication with CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (where token is your password)
SSL Certificate Issues: If using Server/Data Center and encounter SSL errors, set CONFLUENCE_SSL_VERIFY=false or JIRA_SSL_VERIFY=false
Permission Errors: Ensure your Atlassian account has sufficient permissions to access the spaces/projects
Custom Headers Issues: See the "Debugging Custom Headers" section below to analyze and resolve issues with custom headers
To verify custom headers are being applied correctly:
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=trueCheck Header Parsing: Custom headers appear in logs with masked values for security:
DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}Verify Service-Specific Headers: Check logs to confirm the right headers are being used:
DEBUG Jira request headers: service-specific headers applied
DEBUG Confluence request headers: service-specific headers appliedTest Header Format: Ensure your header string format is correct:
# Correct format
JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
CONFLUENCE_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 equalsSecurity Note: Header values containing sensitive information (tokens, passwords) are automatically masked in logs to prevent accidental exposure.
# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...
# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...
# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | moreNever share API tokens
Keep .env files secure and private
See SECURITY.md for best practices
We welcome contributions to MCP Atlassian! If you'd like to contribute:
Check out our CONTRIBUTING.md guide for detailed development setup instructions.
Make changes and submit a pull request.
We use pre-commit hooks for code quality and follow semantic versioning for releases.
Licensed under MIT - see LICENSE file. This is not an official Atlassian product.
Add a comment to a pull request.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID. comment: Comment text. severity: Severity of the blocker. (Normal or Blocker) (default: NORMAL)
Returns: JSON string containing the created comment details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: comment (required), workspace (required), repository (required), pull_request_id (required), +1 more. Returns: Generic wrapper for non-object return types.
Add a comment to a pull request.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID. comment: Comment text.
Returns: JSON string containing the created comment details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: comment (required), workspace (required), repository (required), pull_request_id (required). Returns: Generic wrapper for non-object return types.
Add an inline comment on a specific line of a file in a pull request.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID. comment: Comment text. file_path: Path to the file to comment on. line: Line number to attach the comment to. line_type: Line type for Server/DC ('ADDED', 'REMOVED', or 'CONTEXT').
Returns: JSON string containing the created comment details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: line (required), comment (required), file_path (required), workspace (required), +3 more. Returns: Generic wrapper for non-object return types.
Analyze a pull request's comment threads to determine which review feedback has been addressed and which is still pending.
For each comment thread the tool inspects:
Whether the comment is explicitly resolved/marked done (Server/DC state field,
Cloud resolved flag).
Replies in the thread — if a reply contains completion keywords ("done", "fixed", "addressed", "resolved", "updated", "completed") it is considered addressed even when no formal resolve action was taken.
Returns a structured summary with:
total_comments: number of top-level review comments found
addressed: list of comments considered done (resolved or positively replied)
pending: list of comments that still need attention
overall_status: "ALL_ADDRESSED" | "PARTIALLY_ADDRESSED" | "NONE_ADDRESSED"
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID.
Returns: JSON string with the review status analysis.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), pull_request_id (required). Returns: Generic wrapper for non-object return types.
Create a new branch in a repository.
Args: workspace: Workspace name or project key. repository: Repository name. branch_name: New branch name. source_branch: Source branch to create from (default: main).
Returns: JSON string containing the created branch details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), branch_name (required), source_branch. Returns: Generic wrapper for non-object return types.
Create a new pull request.
Args: workspace: Workspace name or project key. repository: Repository name. title: Pull request title. source_branch: Source branch name. destination_branch: Destination branch name (default: main). description: Optional pull request description.
Returns: JSON string containing the created pull request details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: title (required), workspace (required), repository (required), source_branch (required), +2 more. Returns: Generic wrapper for non-object return types.
Create a new repository in a workspace/project.
Args: ctx: The MCP context. workspace: Workspace name (Cloud) or project key (Server/DC). repo_slug: Repository name/slug to create. is_private: Whether the repository should be private (default: True). forkable: Whether the repository can be forked (default: False).
Returns: JSON string containing the created repository details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: repo_slug (required), workspace (required), forkable, is_private. Returns: Generic wrapper for non-object return types.
Get all CI/CD build statuses for a specific commit.
Returns the full list of pipeline/build results associated with the commit, including the build state (SUCCESSFUL, FAILED, INPROGRESS), build key, name, description, and the URL to the build in the CI system (e.g. Jenkins, Bamboo).
Use this to check whether all required pipelines passed before merging a PR or to identify which specific build failed. If limit is not specified, all builds are returned.
Args: workspace: Workspace name or project key. repository: Repository name. commit_id: Full commit hash to look up builds for. limit: Maximum number of builds to return. If not specified, returns all builds.
Returns: JSON string containing the list of builds with their status and details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: commit_id (required), workspace (required), repository (required), limit. Returns: Generic wrapper for non-object return types.
Get commit history for a repository branch.
Args: workspace: Workspace name or project key. repository: Repository name. commit_id: ID of the commit whose changes are being fetched. merges: Filter merges ('include', 'exclude', 'only') (default: include) hash_newest: Fetch changes for a particular commit hash.
Returns: JSON string containing commit history.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: commit_id (required), workspace (required), repository (required), merges, +1 more. Returns: Generic wrapper for non-object return types.
Get commit history for a repository branch.
Args: workspace: Workspace name or project key. repository: Repository name. until: The commit ID or ref (inclusively) to retrieve commits before limit: Maximum number of commits to return (default: 25). since: The commit ID or ref (inclusively) to retrieve commits after
Returns: JSON string containing commit history.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), limit, since, +1 more. Returns: Generic wrapper for non-object return types.
Get the default branch for a repository.
Args: workspace: Workspace name or project key. repository: Repository name.
Returns: JSON string containing default branch information.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required). Returns: Generic wrapper for non-object return types.
Get the content of a specific file from a repository.
Args: workspace: Workspace name or project key. repository: Repository name. file_path: Path to the file in the repository. branch: Branch name to read from (default: main).
Returns: JSON string containing file content and metadata.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: file_path (required), workspace (required), repository (required), branch, +1 more. Returns: Generic wrapper for non-object return types.
Get detailed information about a specific pull request.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID.
Returns: JSON string containing pull request details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), pull_request_id (required). Returns: Generic wrapper for non-object return types.
Get the list of commits included in a pull request.
Returns each commit's hash, author, timestamp, and commit message so you can trace what changes were introduced and by whom. If limit is not specified, all commits are returned.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID. limit: Maximum number of commits to return. If not specified, returns all commits.
Returns: JSON string containing the list of commits for the pull request.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), pull_request_id (required), limit. Returns: Generic wrapper for non-object return types.
Get the full code diff (all changed files and lines) for a pull request.
Returns the unified diff of all changes included in the PR so you can review exactly what new code was added, modified, or removed.
For Bitbucket Cloud the response is a raw unified diff string. For Bitbucket Server/DC the response is structured JSON containing per-file diff hunks.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID.
Returns: JSON string wrapping the diff content and metadata.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), pull_request_id (required). Returns: Generic wrapper for non-object return types.
Get detailed information about a specific repository.
Args: ctx: The MCP context. workspace: Workspace name or project key. repository: Repository name.
Returns: JSON string containing repository details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required). Returns: Generic wrapper for non-object return types.
List all branches in a repository.
Args: ctx: The MCP context. workspace: Workspace name or project key. repository: Repository name. base: The base branch from which to find branches. branch_filter: Branch pattern to filter on. start: Starting index. limit: Maximum number of branches to fetch.
Returns: JSON string containing list of branches with their details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), base, limit, +2 more. Returns: Generic wrapper for non-object return types.
List the contents of a directory in a repository.
Args: workspace: Workspace name or project key. repository: Repository name. path: Directory path in the repository (empty for root). branch: Branch name to list from (default: main).
Returns: JSON string containing directory contents.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), path, branch. Returns: Generic wrapper for non-object return types.
List pull requests for a repository.
Args: workspace: Workspace name or project key. repository: Repository name. state: Pull request state filter (OPEN, MERGED, DECLINED).
Returns: JSON string containing list of pull requests.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), state. Returns: Generic wrapper for non-object return types.
List repositories in a workspace/project or all accessible repositories.
Args: ctx: The MCP context. workspace: Optional workspace name or project key to filter repositories.
Returns: JSON string containing list of repositories with their details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace. Returns: Generic wrapper for non-object return types.
List all accessible workspaces (Cloud) or projects (Server/DC).
Returns: JSON string containing list of workspaces/projects with their details.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: no named parameters. Returns: Generic wrapper for non-object return types.
Get all activities on a pull request.
Args: workspace: Workspace name or project key. repository: Repository name. pull_request_id: Pull request ID to get comments for.
Returns: JSON string containing list of pull requests.
Raises: ValueError: If the Bitbucket client is not configured or available.
Inputs: workspace (required), repository (required), pull_request_id (required). Returns: Generic wrapper for non-object return types.
Add a comment to a Confluence page.
Args: ctx: The FastMCP context. page_id: The ID of the page to add a comment to. content: The comment content in Markdown format.
Returns: JSON string representing the created comment.
Raises: ValueError: If in read-only mode or Confluence client is unavailable.
Inputs: content (required), page_id (required). Returns: Generic wrapper for non-object return types.
Add label to an existing Confluence page.
Args: ctx: The FastMCP context. page_id: The ID of the page to update. name: The name of the label.
Returns: JSON string representing the updated list of label objects for the page.
Raises: ValueError: If in read-only mode or Confluence client is unavailable.
Inputs: name (required), page_id (required). Returns: Generic wrapper for non-object return types.
Create a new Confluence page.
Args: ctx: The FastMCP context. space_key: The key of the space. title: The title of the page. content: The content of the page (format depends on content_format). parent_id: Optional parent page ID. content_format: The format of the content ('markdown', 'wiki', or 'storage'). enable_heading_anchors: Whether to enable heading anchors (markdown only).
Returns: JSON string representing the created page object.
Raises: ValueError: If in read-only mode, Confluence client is unavailable, or invalid content_format.
Inputs: title (required), content (required), space_key (required), parent_id, +2 more. Returns: Generic wrapper for non-object return types.
Delete an existing Confluence page.
Args: ctx: The FastMCP context. page_id: The ID of the page to delete.
Returns: JSON string indicating success or failure.
Raises: ValueError: If Confluence client is not configured or available.
Inputs: page_id (required). Returns: Generic wrapper for non-object return types.
Get comments for a specific Confluence page.
Args: ctx: The FastMCP context. page_id: Confluence page ID.
Returns: JSON string representing a list of comment objects.
Inputs: page_id (required). Returns: Generic wrapper for non-object return types.
Get labels for a specific Confluence page.
Args: ctx: The FastMCP context. page_id: Confluence page ID.
Returns: JSON string representing a list of label objects.
Inputs: page_id (required). Returns: Generic wrapper for non-object return types.
Get content of a specific Confluence page by its ID, or by its title and space key.
Args: ctx: The FastMCP context. page_id: Confluence page ID. If provided, 'title' and 'space_key' are ignored. title: The exact title of the page. Must be used with 'space_key'. space_key: The key of the space. Must be used with 'title'. include_metadata: Whether to include page metadata. convert_to_markdown: Convert content to markdown (true) or keep raw HTML (false). sample: Return only top N lines or the whole page when set to -1.
Returns: JSON string representing the page content and/or metadata, or an error if not found or parameters are invalid.
Inputs: title, sample, page_id, space_key, +2 more. Returns: Generic wrapper for non-object return types.
Get child pages of a specific Confluence page.
Args: ctx: The FastMCP context. parent_id: The ID of the parent page. expand: Fields to expand. limit: Maximum number of child pages. include_content: Whether to include page content. convert_to_markdown: Convert content to markdown if include_content is true. start: Starting index for pagination.
Returns: JSON string representing a list of child page objects.
Inputs: parent_id (required), limit, start, expand, +2 more. Returns: Generic wrapper for non-object return types.
Search Confluence content using simple terms or CQL.
Args: ctx: The FastMCP context. query: Search query - can be simple text or a CQL query string. limit: Maximum number of results (1-50). spaces_filter: Comma-separated list of space keys to filter by.
Returns: JSON string representing a list of simplified Confluence page objects.
Inputs: query (required), limit, spaces_filter. Returns: Generic wrapper for non-object return types.
Search Confluence users using CQL.
Args: ctx: The FastMCP context. query: Search query - a CQL query string for user search. limit: Maximum number of results (1-50).
Returns: JSON string representing a list of simplified Confluence user search result objects.
Inputs: query (required), limit. Returns: Generic wrapper for non-object return types.
Update an existing Confluence page.
Args: ctx: The FastMCP context. page_id: The ID of the page to update. title: The new title of the page. content: The new content of the page (format depends on content_format). is_minor_edit: Whether this is a minor edit. version_comment: Optional comment for this version. parent_id: Optional new parent page ID. content_format: The format of the content ('markdown', 'wiki', or 'storage'). enable_heading_anchors: Whether to enable heading anchors (markdown only).
Returns: JSON string representing the updated page object.
Raises: ValueError: If Confluence client is not configured, available, or invalid content_format.
Inputs: title (required), content (required), page_id (required), parent_id, +4 more. Returns: Generic wrapper for non-object return types.
Add a comment to a Jira issue.
Args: ctx: The FastMCP context. issue_key: Jira issue key. comment: Comment text in Markdown.
Returns: JSON string representing the added comment object.
Raises: ValueError: If in read-only mode or Jira client unavailable.
Inputs: comment (required), issue_key (required). Returns: Generic wrapper for non-object return types.
Add a worklog entry to a Jira issue.
Args: ctx: The FastMCP context. issue_key: Jira issue key. time_spent: Time spent in Jira format. comment: Optional comment in Markdown. started: Optional start time in ISO format. original_estimate: Optional new original estimate. remaining_estimate: Optional new remaining estimate.
Returns: JSON string representing the added worklog object.
Raises: ValueError: If in read-only mode or Jira client unavailable.
Inputs: issue_key (required), time_spent (required), comment, started, +2 more. Returns: Generic wrapper for non-object return types.
Create multiple Jira issues in a batch.
Args: ctx: The FastMCP context. issues: Issue objects as an array or a JSON-encoded array string. validate_only: If true, only validates without creating.
Returns: JSON string indicating success and listing created issues (or validation result).
Raises: ValueError: If in read-only mode, Jira client unavailable, or input is invalid.
Inputs: issues (required), validate_only. Returns: Generic wrapper for non-object return types.
Batch create multiple versions in a Jira project.
Args: ctx: The FastMCP context. project_key: The project key. versions: JSON array string of version objects.
Returns: JSON array of results, each with success flag, version or error.
Inputs: versions (required), project_key (required). Returns: Generic wrapper for non-object return types.
Get changelogs for multiple Jira issues (Cloud only).
Args: ctx: The FastMCP context. issue_ids_or_keys: List of issue IDs or keys. fields: List of fields to filter changelogs by. None for all fields. limit: Maximum changelogs per issue (-1 for all).
Returns: JSON string representing a list of issues with their changelogs.
Raises: NotImplementedError: If run on Jira Server/Data Center. ValueError: If Jira client is unavailable.
Inputs: issue_ids_or_keys (required), limit, fields. Returns: Generic wrapper for non-object return types.
Clone an existing Jira issue by copying its fields into a new issue.
Jira does not provide a single "clone issue" REST endpoint on Data Center, Server, or Cloud. This tool reproduces the Jira UI's built-in Clone action: it fetches the source issue's fields, creates a new issue with those fields copied over (summary, description, issue type, priority, labels, components, fix/affects versions, assignee, due date, security level, environment, and populated custom fields), and links the new issue back to the source issue with a "Cloners" issue link.
Each standard and custom field is pre-verified against the target project's create screen metadata before being copied, so fields that are not available for that project/issue type are excluded individually instead of failing the whole clone. Any excluded fields are listed under "excluded_fields" in the response.
Args: ctx: The FastMCP context. issue_key: The key of the issue to clone. project_key: Optional target project key. summary: Optional summary override for the clone. include_custom_fields: Whether to copy populated custom fields. link_to_original: Whether to create a "Cloners" link back to the source issue. include_links: Whether to re-create the source issue's other issue links. additional_fields: Optional dictionary of fields to override or add.
Returns: JSON string representing the newly created clone issue. Includes an "excluded_fields" list when fields were skipped because they are not on the target create screen.
Raises: ValueError: If in read-only mode, Jira client unavailable, or the source issue/target project is invalid.
Inputs: issue_key (required), summary, project_key, include_links, +3 more. Returns: Generic wrapper for non-object return types.
Return a short-lived authenticated download URL for a cached Jira attachment.
This is intended for clients that need a regular HTTP URL instead of an MCP resource URI. The attachment must already be present in the in-memory cache, typically by running jira_download_attachments with return_content=true.
Args: ctx: The FastMCP context. issue_key: Jira issue key for the cached attachment. filename: Cached attachment filename. ttl_minutes: Download URL lifetime in minutes (max 10).
Returns: JSON string with download_url, expires_at, and attachment metadata.
Inputs: filename (required), issue_key (required), ttl_minutes. Returns: Generic wrapper for non-object return types.
Return the URL and session token needed to upload local files to the MCP server.
This is step 1 of the client-side file upload flow:
Call this tool to get upload_url + session_id.
POST your file(s) to upload_url using multipart/form-data with the Mcp-Session-Id header set to session_id.
Windows PowerShell (handles paths with spaces): curl.exe -X POST <upload_url> -H "Mcp-Session-Id: " -F 'file=@"C:\path with spaces\file.pdf"'
Linux / macOS (handles paths with spaces): curl -X POST <upload_url> -H "Mcp-Session-Id: " -F "file=@'/path/with spaces/file.pdf'"
The server returns: {"uploaded": [{"filename": "...", "uri": "upload://...", "size": ...}]}
Pass the returned upload:// URIs to jira_upload_attachment.
Sessions expire after 30 minutes (configurable via UPLOAD_STAGING_TTL_MINUTES). The base URL defaults to http://localhost:8932 and can be overridden by the MCP_SERVER_BASE_URL environment variable.
Args: ctx: The FastMCP context.
Returns: JSON string with upload_url, session_id, required_headers, and OS-specific usage example.
Inputs: no named parameters. Returns: Generic wrapper for non-object return types.
Create a new Jira issue with optional Epic link or parent for subtasks.
Args: ctx: The FastMCP context. project_key: The JIRA project key. summary: Summary/title of the issue. issue_type: Issue type (e.g., 'Task', 'Bug', 'Story', 'Epic', 'Subtask'). assignee: Assignee's user identifier (string): Email, display name, or account ID (e.g., 'user@example.com', 'John Doe', 'accountid:...'). description: Issue description. components: Comma-separated list of component names. additional_fields: Dictionary of additional fields.
Returns: JSON string representing the created issue object.
Raises: ValueError: If in read-only mode or Jira client is unavailable.
Inputs: summary (required), issue_type (required), project_key (required), assignee, +3 more. Returns: Generic wrapper for non-object return types.
Create a link between two Jira issues.
Args: ctx: The FastMCP context. link_type: The type of link (e.g., 'Blocks'). inward_issue_key: The key of the source issue. outward_issue_key: The key of the target issue. comment: Optional comment text. comment_visibility: Optional dictionary for comment visibility.
Returns: JSON string indicating success or failure.
Raises: ValueError: If required fields are missing, invalid input, in read-only mode, or Jira client unavailable.
Inputs: link_type (required), inward_issue_key (required), outward_issue_key (required), comment, +1 more. Returns: Generic wrapper for non-object return types.
Create a remote issue link (web link or Confluence link) for a Jira issue.
This tool allows you to add web links and Confluence links to Jira issues. The links will appear in the issue's "Links" section and can be clicked to navigate to external resources.
Args: ctx: The FastMCP context. issue_key: The key of the issue to add the link to. url: The URL to link to (can be any web page or Confluence page). title: The title/name that will be displayed for the link. summary: Optional description of what the link is for. relationship: Optional relationship description. icon_url: Optional URL to a 16x16 icon for the link.
Returns: JSON string indicating success or failure.
Raises: ValueError: If required fields are missing, invalid input, in read-only mode, or Jira client unavailable.
Inputs: url (required), title (required), issue_key (required), summary, +2 more. Returns: Generic wrapper for non-object return types.
Create Jira sprint for a board.
Args: ctx: The FastMCP context. board_id: Board ID. sprint_name: Sprint name. start_date: Start date (ISO format). end_date: End date (ISO format). goal: Optional sprint goal.
Returns: JSON string representing the created sprint object.
Raises: ValueError: If in read-only mode or Jira client unavailable.
Inputs: board_id (required), end_date (required), start_date (required), sprint_name (required), +1 more. Returns: Generic wrapper for non-object return types.
Create a new fix version in a Jira project.
Args: ctx: The FastMCP context. project_key: The project key. name: Name of the version. start_date: Start date (optional). release_date: Release date (optional). description: Description (optional).
Returns: JSON string of the created version object.
Inputs: name (required), project_key (required), start_date, description, +1 more. Returns: Generic wrapper for non-object return types.
Delete an existing Jira issue.
Args: ctx: The FastMCP context. issue_key: Jira issue key.
Returns: JSON string indicating success.
Raises: ValueError: If in read-only mode or Jira client unavailable.
Inputs: issue_key (required). Returns: Generic wrapper for non-object return types.
Download attachments from a Jira issue to disk, MCP resources, or both.
When resource caching is enabled, each attachment is immediately available in the MCP resource browser via a static URI — no cache key required:
jira://attachments/{issue_key}/{filename}Examples: jira://attachments/JDQU-2322/desktop-screenshot-1.png ← renders as image jira://attachments/JDQU-2322/SPyDR%20Metadata.txt ← opens as text
Cached resources are valid for 10 minutes. Re-run this tool to refresh.
Args: ctx: The FastMCP context. issue_key: Jira issue key (e.g., 'PROJ-123'). target_dir: Optional server-side save path for downloaded files. return_content: Optional flag to cache attachments as MCP resources.
Returns: JSON string with download results. Attachments may include: - filename: The attachment filename - size: File size in bytes - path: Server-side download path when target_dir is provided - static_resource_uri: Direct MCP resource URI when return_content is enabled - mime_type: MIME type of the file when return_content is enabled
Inputs: issue_key (required), target_dir, return_content. Returns: Generic wrapper for non-object return types.
Get jira agile boards by name, project key, or type.
Args: ctx: The FastMCP context. board_name: Name of the board (fuzzy search). project_key: Project key. board_type: Board type ('scrum' or 'kanban'). start_at: Starting index. limit: Maximum results.
Returns: JSON string representing a list of board objects.
Inputs: limit, start_at, board_name, board_type, +1 more. Returns: Generic wrapper for non-object return types.
Get all Jira projects accessible to the current user.
Args: ctx: The FastMCP context. include_archived: Whether to include archived projects.
Returns: JSON string representing a list of project objects accessible to the user. Project keys are always returned in uppercase. If JIRA_PROJECTS_FILTER is configured, only returns projects matching those keys.
Raises: ValueError: If the Jira client is not configured or available.
Inputs: include_archived. Returns: Generic wrapper for non-object return types.
Fetch image attachments from a Jira issue as viewable image content.
Returns each image as an MCP image content block so a vision-capable model can see and describe it directly — no MarkItDown text extraction and no MCP sampling required. Works with any client whose own model supports images (e.g., Claude, GPT-4o, Bedrock vision models).
Non-image attachments are ignored; use jira_summarize_attachments for
documents (PDF / DOCX / XLSX / CSV / …).
Args: ctx: The FastMCP context. issue_key: Jira issue key (e.g., 'PROJ-123'). filename_filter: Optional comma-separated list of image filenames to fetch. max_images: Maximum number of images to return (default: 10).
Returns: A ToolResult whose content holds one image block per attachment (each preceded by a text label) and whose structured content lists the image metadata plus any download failures.
Inputs: issue_key (required), max_images, filename_filter.
Get all issues linked to a specific board filtered by JQL.
Args: ctx: The FastMCP context. board_id: The ID of the board. jql: JQL query string to filter issues. fields: Comma-separated fields to return. start_at: Starting index for pagination. limit: Maximum number of results. expand: Optional fields to expand.
Returns: JSON string representing the search results including pagination info.
Inputs: jql (required), board_id (required), limit, expand, +2 more. Returns: Generic wrapper for non-object return types.
Get details of a specific Jira issue including its Epic links and relationship information.
Args: ctx: The FastMCP context. issue_key: Jira issue key. fields: Comma-separated list of fields to return (e.g., 'summary,status,customfield_10010'), a single field as a string (e.g., 'duedate'), '*all' for all fields, or omitted for essentials. expand: Optional fields to expand. comment_limit: Maximum number of comments. properties: Issue properties to return. update_history: Whether to update issue view history.
Returns: JSON string representing the Jira issue object.
Raises: ValueError: If the Jira client is not configured or available.
Inputs: issue_key (required), expand, fields, properties, +2 more. Returns: Generic wrapper for non-object return types.
Get all available issue link types.
Args: ctx: The FastMCP context.
Returns: JSON string representing a list of issue link type objects.
Inputs: no named parameters. Returns: Generic wrapper for non-object return types.
Get all issues for a specific Jira project.
Args: ctx: The FastMCP context. project_key: The project key. limit: Maximum number of results. start_at: Starting index for pagination.
Returns: JSON string representing the search results including pagination info.
Inputs: project_key (required), limit, start_at. Returns: Generic wrapper for non-object return types.
Get all fix versions for a specific Jira project.
Inputs: project_key (required). Returns: Generic wrapper for non-object return types.
Get jira issues from sprint.
Args: ctx: The FastMCP context. sprint_id: The ID of the sprint. fields: Comma-separated fields to return. start_at: Starting index. limit: Maximum results.
Returns: JSON string representing the search results including pagination info.
Inputs: sprint_id (required), limit, fields, start_at. Returns: Generic wrapper for non-object return types.
Get jira sprints from board by state.
Args: ctx: The FastMCP context. board_id: The ID of the board. state: Sprint state ('active', 'future', 'closed'). If None, returns all sprints. start_at: Starting index. limit: Maximum results.
Returns: JSON string representing a list of sprint objects.
Inputs: board_id (required), limit, state, start_at. Returns: Generic wrapper for non-object return types.
Get available status transitions for a Jira issue.
Args: ctx: The FastMCP context. issue_key: Jira issue key.
Returns: JSON string representing a list of available transitions.
Inputs: issue_key (required). Returns: Generic wrapper for non-object return types.
Retrieve profile information for a specific Jira user.
Args: ctx: The FastMCP context. user_identifier: User identifier (email, username, key, or account ID).
Returns: JSON string representing the Jira user profile object, or an error object if not found.
Raises: ValueError: If the Jira client is not configured or available.
Inputs: user_identifier (required). Returns: Generic wrapper for non-object return types.
Get worklog entries for a Jira issue.
Args: ctx: The FastMCP context. issue_key: Jira issue key.
Returns: JSON string representing the worklog entries.
Inputs: issue_key (required). Returns: Generic wrapper for non-object return types.
Upload one or more staged files to a Jira issue as attachments.
This is step 3 of the client-side file upload flow (after construct_upload_endpoint and POSTing files to /upload).
Each upload:// URI is resolved from the server-side staging store, then uploaded directly to Jira via the REST API — no base64, no context-window overhead.
Staged files are removed from the store after a successful upload. Unused uploads expire automatically after 30 minutes.
Args: ctx: The FastMCP context. issue_key: Jira issue key (e.g., 'PROJ-123'). upload_uris: List of upload:// URIs from the /upload endpoint response.
Returns: JSON string with per-file upload results.
Raises: ValueError: If in read-only mode or Jira client is unavailable.
Inputs: issue_key (required), upload_uris (required). Returns: Generic wrapper for non-object return types.
Link an existing issue to an epic.
Args: ctx: The FastMCP context. issue_key: The key of the issue to link. epic_key: The key of the epic to link to.
Returns: JSON string representing the updated issue object.
Raises: ValueError: If in read-only mode or Jira client unavailable.
Inputs: epic_key (required), issue_key (required). Returns: Generic wrapper for non-object return types.
List all currently cached attachments available via MCP resources.
Each attachment exposes a static_resource_uri that can be opened directly in the MCP resource browser without knowing the cache key:
jira://attachments/{issue_key}/{filename}Images (PNG, JPEG, etc.) render inline. Text files open as-is. All cached resources expire after 10 minutes.
Returns: JSON string with list of cached attachments including URIs and metadata
Inputs: no named parameters. Returns: Generic wrapper for non-object return types.
Remove a link between two Jira issues.
Args: ctx: The FastMCP context. link_id: The ID of the link to remove.
Returns: JSON string indicating success.
Raises: ValueError: If link_id is missing, in read-only mode, or Jira client unavailable.
Inputs: link_id (required). Returns: Generic wrapper for non-object return types.
Save a cached attachment to the MCP SERVER's filesystem.
⚠️ WARNING: This saves to the SERVER's filesystem, NOT your local client machine!
Use cases:
MCP server is running locally on your machine
Need to save files on a remote server for server-side processing
Saving to a shared network location accessible from server
For CLIENT-SIDE saving (your local VS Code machine):
Use the resource URI from download_attachments response
Your MCP client (VS Code) will fetch and save it locally
Args: ctx: The FastMCP context. cache_key: The cache_key returned from download_attachments tool target_path: Full file path on SERVER filesystem (not client's local disk)
Returns: JSON string with save result including absolute path on server
Example: # This saves to SERVER filesystem, not your local machine! save_attachment_to_disk( cache_key="abc123def456", target_path="/server/storage/design.pdf" )
Inputs: cache_key (required), target_path (required). Returns: Generic wrapper for non-object return types.
Search Jira issues using JQL (Jira Query Language).
Args: ctx: The FastMCP context. jql: JQL query string. fields: Comma-separated fields to return. limit: Maximum number of results. start_at: Starting index for pagination. projects_filter: Comma-separated list of project keys to filter by. expand: Optional fields to expand.
Returns: JSON string representing the search results including pagination info.
Inputs: jql (required), limit, expand, fields, +2 more. Returns: Generic wrapper for non-object return types.
Search Jira fields by keyword with fuzzy match.
Args: ctx: The FastMCP context. keyword: Keyword for fuzzy search. limit: Maximum number of results. refresh: Whether to force refresh the field list.
Returns: JSON string representing a list of matching field definitions.
Inputs: limit, keyword, refresh. Returns: Generic wrapper for non-object return types.
Scan and summarize attachments (PDFs, images, Office documents) from a Jira issue.
Uses Microsoft MarkItDown to extract readable content from each supported attachment:
• PDF → full text extracted via pdfminer • Images → EXIF metadata (for a visual description use jira_get_attachment_images) • DOCX / PPTX / XLSX → document text and structure as Markdown • CSV / JSON / XML → raw content rendered as Markdown
Unsupported file types (e.g., zip, mp4, exe) are skipped and listed under
"skipped" in the response.
Requires the markitdown package — add it with:
uv add 'markitdown[pdf]'
To have a vision-capable model see image attachments (screenshots, diagrams,
charts), use jira_get_attachment_images instead — it returns the raw images
as content blocks your model can view directly.
Args: ctx: The FastMCP context. issue_key: Jira issue key (e.g., 'PROJ-123'). filename_filter: Optional comma-separated list of filenames to process. max_chars_per_file: Truncation limit per file in characters (0 = unlimited).
Returns: JSON string with per-attachment summaries including extracted markdown content.
Inputs: issue_key (required), filename_filter, max_chars_per_file. Returns: Generic wrapper for non-object return types.
Transition a Jira issue to a new status.
Args: ctx: The FastMCP context. issue_key: Jira issue key. transition_id: ID of the transition. fields: Optional dictionary of fields to update during transition. comment: Optional comment for the transition.
Returns: JSON string representing the updated issue object.
Raises: ValueError: If required fields missing, invalid input, in read-only mode, or Jira client unavailable.
Inputs: issue_key (required), transition_id (required), fields, comment. Returns: Generic wrapper for non-object return types.
Update an existing Jira issue including changing status, adding Epic links, updating fields, etc.
Args: ctx: The FastMCP context. issue_key: Jira issue key. fields: Dictionary of fields to update. additional_fields: Optional dictionary of additional fields. update: Optional dictionary of Jira "update" operations (add/remove/set) for fields that cannot be set via a direct overwrite. attachments: Optional JSON array string or comma-separated list of file paths.
Returns: JSON string representing the updated issue object and attachment results.
Raises: ValueError: If in read-only mode or Jira client unavailable, or invalid input.
Inputs: fields (required), issue_key (required), update, attachments, +1 more. Returns: Generic wrapper for non-object return types.
Update jira sprint.
Args: ctx: The FastMCP context. sprint_id: The ID of the sprint. sprint_name: Optional new name. state: Optional new state (future|active|closed). start_date: Optional new start date. end_date: Optional new end date. goal: Optional new goal.
Returns: JSON string representing the updated sprint object or an error message.
Raises: ValueError: If in read-only mode or Jira client unavailable.
Inputs: sprint_id (required), goal, state, end_date, +2 more. Returns: Generic wrapper for non-object return types.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 73 tools
Most tools target distinct resources, but the attachment cluster (jira_download_attachments, jira_save_attachment_to_disk, jira_get_attachment_images, jira_summarize_attachments, jira_construct_download_endpoint) overlaps heavily. Critically, bitbucket_get_commit_changes and bitbucket_get_commits have nearly identical descriptions ('Get commit history for a repository branch'), making them hard to tell apart.
Names follow a consistent product_action noun pattern with jira_, confluence_, and bitbucket_ prefixes. The main deviation is the anomalous jira_jira_upload_attachment with a doubled prefix, plus a few slightly verbose names, but overall the convention is predictable.
73 tools is excessive; even accounting for spanning Jira, Confluence, and Bitbucket, this is far above a well-scoped set. Many granular attachment, comment, and commit tools could be consolidated or made configurable.
Coverage is broad across all three products: Jira issues/sprints/boards/versions/links/worklogs/attachments/transitions, Confluence pages/comments/labels/search, and Bitbucket repos/branches/PRs/commits/builds. Minor gaps remain (no delete-comment, no PR update/merge, no delete-sprint), but core lifecycles are covered.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for building and testing AI agents with multi-model experimentation and insights.