# Docker Deployment
Source: https://mcp-atlassian.soomiles.com/docs/advanced/docker-production
Deploy MCP Atlassian with Docker for production — Compose examples, health checks, and Kubernetes notes
MCP Atlassian provides Docker images for production deployment. This guide covers Docker Compose setups, health checks, and orchestration patterns.
## Quick Start
```bash theme={null}
docker run -i --rm \
-e JIRA_URL=https://your-company.atlassian.net \
-e JIRA_USERNAME=your.email@example.com \
-e JIRA_API_TOKEN=your_api_token \
-e CONFLUENCE_URL=https://your-company.atlassian.net/wiki \
-e CONFLUENCE_USERNAME=your.email@example.com \
-e CONFLUENCE_API_TOKEN=your_api_token \
ghcr.io/sooperset/mcp-atlassian:latest
```
## Docker Compose
### Basic Setup
```yaml theme={null}
version: "3.8"
services:
mcp-atlassian:
image: ghcr.io/sooperset/mcp-atlassian:latest
env_file: .env
ports:
- "8000:8000"
environment:
- TRANSPORT=sse
- PORT=8000
- HOST=0.0.0.0
restart: unless-stopped
```
### With Health Checks
```yaml theme={null}
version: "3.8"
services:
mcp-atlassian:
image: ghcr.io/sooperset/mcp-atlassian:latest
env_file: .env
ports:
- "8000:8000"
environment:
- TRANSPORT=sse
- PORT=8000
- HOST=0.0.0.0
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
restart: unless-stopped
```
### Multi-Service Setup
Run separate Jira and Confluence services:
```yaml theme={null}
version: "3.8"
services:
jira-mcp:
image: ghcr.io/sooperset/mcp-atlassian:latest
env_file: .env.jira
ports:
- "8001:8000"
environment:
- TRANSPORT=sse
- PORT=8000
- ENABLED_TOOLS=jira_search,jira_get_issue,jira_create_issue,jira_update_issue
confluence-mcp:
image: ghcr.io/sooperset/mcp-atlassian:latest
env_file: .env.confluence
ports:
- "8002:8000"
environment:
- TRANSPORT=sse
- PORT=8000
- ENABLED_TOOLS=confluence_search,confluence_get_page,confluence_create_page
```
## Environment File Pattern
Use `.env` files for sensitive credentials:
```bash theme={null}
# .env
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@example.com
JIRA_API_TOKEN=your_api_token
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@example.com
CONFLUENCE_API_TOKEN=your_api_token
```
Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
## Read-Only Mode
For production environments where write operations should be disabled:
```yaml theme={null}
environment:
- READ_ONLY_MODE=true
```
This disables all create, update, and delete tools at the server level.
## Kubernetes Notes
For Kubernetes deployments:
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-atlassian
spec:
replicas: 1
selector:
matchLabels:
app: mcp-atlassian
template:
metadata:
labels:
app: mcp-atlassian
spec:
containers:
- name: mcp-atlassian
image: ghcr.io/sooperset/mcp-atlassian:latest
ports:
- containerPort: 8000
env:
- name: TRANSPORT
value: "sse"
- name: PORT
value: "8000"
envFrom:
- secretRef:
name: atlassian-credentials
livenessProbe:
httpGet:
path: /healthz
port: 8000
initialDelaySeconds: 10
periodSeconds: 30
readinessProbe:
httpGet:
path: /healthz
port: 8000
initialDelaySeconds: 5
periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
name: mcp-atlassian
spec:
selector:
app: mcp-atlassian
ports:
- port: 8000
targetPort: 8000
```
Use Kubernetes Secrets for credentials. Create with: `kubectl create secret generic atlassian-credentials --from-env-file=.env`
For high availability, consider running separate deployments for Jira and Confluence services with different `ENABLED_TOOLS` configurations.
# SLA Metrics
Source: https://mcp-atlassian.soomiles.com/docs/advanced/sla-metrics
Configure and use SLA metrics for Jira issues — cycle time, lead time, time-in-status, and more
MCP Atlassian can calculate SLA metrics for Jira issues using the `jira_get_issue_sla` and `jira_get_issue_dates` tools. This guide covers configuration and usage.
## Available Metrics
| Metric | Description |
| --------------------- | ---------------------------------------------------- |
| `cycle_time` | Time from first "In Progress" to resolution |
| `lead_time` | Time from creation to resolution |
| `time_in_status` | Breakdown of time spent in each status |
| `due_date_compliance` | Whether issues were resolved before their due date |
| `resolution_time` | Total time from creation to resolution |
| `first_response_time` | Time from creation to first comment or status change |
## Configuration
Configure SLA calculation via environment variables:
### Metrics Selection
Choose which metrics to calculate (comma-separated):
```bash theme={null}
JIRA_SLA_METRICS=cycle_time,time_in_status
```
Default: `cycle_time,time_in_status`
### Working Hours
Enable business-hours-only calculation:
```bash theme={null}
# Enable working hours filtering
JIRA_SLA_WORKING_HOURS_ONLY=true
# Define business hours (24-hour format)
JIRA_SLA_WORKING_HOURS_START=09:00
JIRA_SLA_WORKING_HOURS_END=17:00
# Working days (1=Monday, 7=Sunday)
JIRA_SLA_WORKING_DAYS=1,2,3,4,5
```
### Timezone
Set the timezone for SLA calculations:
```bash theme={null}
JIRA_SLA_TIMEZONE=America/New_York
```
Uses IANA timezone identifiers. Default: `UTC`
**Common timezones:**
| Timezone | Identifier |
| ----------------- | --------------------- |
| US Eastern | `America/New_York` |
| US Pacific | `America/Los_Angeles` |
| UK | `Europe/London` |
| Central Europe | `Europe/Berlin` |
| Japan | `Asia/Tokyo` |
| Australia Eastern | `Australia/Sydney` |
## Usage
### Get SLA Metrics for an Issue
```json theme={null}
jira_get_issue_sla: {
"issue_key": "PROJ-123",
"metrics": "cycle_time,time_in_status,lead_time"
}
```
### Get Key Dates
```json theme={null}
jira_get_issue_dates: {
"issue_key": "PROJ-123"
}
```
Returns creation date, resolution date, due date, and status transition timestamps.
### Get Development Info
Track linked branches, commits, and PRs:
```json theme={null}
jira_get_issue_development_info: {
"issue_key": "PROJ-123"
}
```
### Batch Development Info
Get development info for multiple issues:
```json theme={null}
jira_get_issues_development_info: {
"issue_keys": "PROJ-1,PROJ-2,PROJ-3"
}
```
## Example Configuration
A typical production SLA configuration:
```bash theme={null}
# Calculate cycle time and time-in-status
JIRA_SLA_METRICS=cycle_time,time_in_status,lead_time
# Count only business hours
JIRA_SLA_WORKING_HOURS_ONLY=true
JIRA_SLA_WORKING_HOURS_START=09:00
JIRA_SLA_WORKING_HOURS_END=17:00
JIRA_SLA_WORKING_DAYS=1,2,3,4,5
# US Eastern timezone
JIRA_SLA_TIMEZONE=America/New_York
```
Start with `cycle_time` and `time_in_status` — these are the most commonly useful metrics for sprint retrospectives and process improvement.
SLA calculations use issue changelog data. For accurate metrics, ensure issues follow consistent status transitions in your workflow.
# Authentication
Source: https://mcp-atlassian.soomiles.com/docs/authentication
Configure authentication for MCP Atlassian — API tokens, PATs, and OAuth 2.0
MCP Atlassian supports three authentication methods depending on your Atlassian deployment type.
## API Token (Cloud) - Recommended
The simplest method for Atlassian Cloud users.
Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
Click **Create API token**, give it a name
Copy the token immediately - you won't see it again
**Environment variables:**
```bash theme={null}
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your_api_token
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your_api_token
```
## Personal Access Token (Server/Data Center)
For Server or Data Center deployments.
Go to your profile (avatar) → **Profile** → **Personal Access Tokens**
Click **Create token**, name it, set expiry
Copy the token immediately
**Environment variables:**
```bash theme={null}
JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=your_personal_access_token
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=your_personal_access_token
```
For self-signed certificates, set `JIRA_SSL_VERIFY=false` and/or `CONFLUENCE_SSL_VERIFY=false`.
## OAuth 2.0 (Cloud) - Advanced
OAuth 2.0 provides enhanced security features but requires more setup. For most users, API Token authentication is simpler and sufficient.
### Setup Steps
Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and create an "OAuth 2.0 (3LO) integration" app
Add scopes for Jira/Confluence as needed
Set to `http://localhost:8080/callback`
```bash theme={null}
# Using uvx
uvx mcp-atlassian --oauth-setup -v
# Or using Docker
docker run --rm -i \
-p 8080:8080 \
-v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
```
Follow prompts for Client ID, Secret, URI, and Scope, then complete browser authorization
**Environment variables (after setup):**
```bash theme={null}
JIRA_URL=https://your-company.atlassian.net
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_wizard
ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_client_id
ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_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
```
Include `offline_access` in your scope to allow automatic token refresh.
### Bring Your Own Token (BYOT)
If you manage OAuth tokens externally (e.g., through a central identity provider):
```bash theme={null}
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id
ATLASSIAN_OAUTH_ACCESS_TOKEN=your_pre_existing_access_token
```
Token refresh is your responsibility - the server does not handle it for BYOT.
### Multi-Cloud OAuth
For multi-tenant applications where users provide their own OAuth tokens:
1. Enable minimal OAuth mode:
```bash theme={null}
# Using uvx
ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000
# Or using Docker
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 `
* `X-Atlassian-Cloud-Id: `
See [HTTP Transport](/docs/http-transport) for more details on multi-user authentication.
# AI Platform Compatibility
Source: https://mcp-atlassian.soomiles.com/docs/compatibility
Platform compatibility matrix — Claude Desktop, Cursor, Cline, and Cloud vs Server/DC feature comparison
MCP Atlassian works with any MCP-compatible client. This page documents platform-specific notes and known issues.
## Compatibility Matrix
| Platform | Status | Transport | Notes |
| ---------------------- | --------------- | ------------ | ----------------------------------------- |
| Claude Desktop | Fully supported | stdio | Primary development target |
| Cursor | Fully supported | stdio | |
| Windsurf | Fully supported | stdio | |
| VS Code (Copilot) | Supported | stdio | See [Copilot setup](#github-copilot) |
| Vertex AI / Google ADK | Supported | stdio / HTTP | Schema sanitization applied automatically |
| Amazon Bedrock | Compatible | stdio / HTTP | Not explicitly tested |
| LiteLLM | Compatible | stdio / HTTP | Passes schemas to underlying provider |
| OpenAI Gateway | Compatible | stdio / HTTP | |
| ChatGPT | Not tested | HTTP | See [ChatGPT notes](#chatgpt) |
## Schema Compatibility
MCP Atlassian includes automatic schema sanitization to ensure compatibility with strict AI platforms:
* **`anyOf` flattening**: Pydantic v2 generates `anyOf` patterns for optional parameters (`T | None`). These are automatically collapsed to simple `{"type": T}` before schemas are sent to clients, since Vertex AI and Google ADK reject `anyOf` alongside `default` or `description` fields.
* **No zero-argument tools**: All tools have at least one parameter, which is required by some OpenAI-compatible gateways.
* **All properties have explicit `type`**: Required by Vertex AI.
* **No `$defs` / `$ref`**: All schemas are fully inlined.
These constraints are enforced by CI tests across all tools.
## Platform-Specific Notes
### GitHub Copilot
GitHub Copilot's coding agent supports MCP servers via stdio transport. Key configuration notes:
Copilot's agent mode uses stdio, not HTTP. Configure as a standard MCP server:
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://your-instance.atlassian.net",
"JIRA_USERNAME": "your-email@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
```
If Copilot reports "Retrieved 0 tools", ensure you are using `mcp-atlassian >= 0.16.0` (which includes FastMCP updates for better protocol compliance).
When using Docker, expose via stdio (not HTTP):
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "JIRA_URL=https://your-instance.atlassian.net",
"-e", "JIRA_USERNAME=your-email@example.com",
"-e", "JIRA_API_TOKEN=your-api-token",
"ghcr.io/sooperset/mcp-atlassian:latest"
]
}
}
}
```
### Vertex AI / Google ADK
Vertex AI enforces strict JSON Schema validation. The automatic `anyOf` flattening resolves the `INVALID_ARGUMENT` errors previously reported with Google ADK.
If you encounter schema errors, ensure you are running the latest version:
```bash theme={null}
uvx mcp-atlassian@latest
```
### ChatGPT
ChatGPT's MCP integration has reported vague "violates guidelines" errors. This may be related to schema validation but no specific diagnostics are available. If you encounter this, please [open an issue](https://github.com/sooperset/mcp-atlassian/issues) with the exact error message.
## HTTP Transport
For platforms that require HTTP transport (e.g., remote deployments, gateways), see the [HTTP Transport](/docs/http-transport) guide.
## Cloud vs Server/Data Center
MCP Atlassian supports both Atlassian Cloud and Server/Data Center deployments, but some features differ between platforms.
### Authentication Methods
| Method | Cloud | Server/DC |
| ---------------------------- | --------- | ------------------------- |
| API Token (username + token) | Yes | Yes (username + password) |
| Personal Access Token (PAT) | No | Yes |
| OAuth 2.0 | Yes (3LO) | Yes (Application Links) |
| BYOT (Bring Your Own Token) | Yes | Yes |
### Tool Availability
| Tool | Cloud | Server/DC | Notes |
| ------------------------------- | ----- | --------- | --------------------------------------------- |
| `jira_batch_get_changelogs` | Yes | No | Cloud-only changelog API |
| `jira_get_issue_proforma_forms` | Yes | No | Cloud-only (requires cloud\_id for Forms API) |
| `jira_get_service_desk_queues` | Yes | Yes | Requires Jira Service Management |
| `confluence_get_page_views` | Yes | No | Cloud-only analytics API |
### Content Format Differences
| Feature | Cloud | Server/DC |
| ------------------- | ------------------------------- | ----------------------------- |
| Issue descriptions | ADF (Atlassian Document Format) | Wiki markup |
| Confluence pages | Storage format (XHTML) | Storage format (XHTML) |
| Markdown input | Auto-converted to ADF | Auto-converted to wiki markup |
| Rich text rendering | ADF JSON | Wiki markup |
MCP Atlassian handles format conversion automatically — you always write in Markdown regardless of platform. The tools convert to the appropriate format (ADF for Cloud, wiki markup for Server/DC).
### API Differences
| Aspect | Cloud | Server/DC |
| ---------------- | ------------------------ | ----------------------- |
| Base URL | `*.atlassian.net` | Custom domain |
| API version | REST API v2 + v3 | REST API v2 |
| User identifiers | `accountId` | `username` or `userKey` |
| Rate limiting | Enforced (\~100 req/min) | Instance-dependent |
| Webhooks | Cloud-managed | Self-managed |
When switching between Cloud and Server/DC, custom field IDs will be different. Use `jira_search_fields` to discover the correct field IDs for your instance.
# Configuration
Source: https://mcp-atlassian.soomiles.com/docs/configuration
Configure MCP Atlassian for Claude Desktop, Cursor, Windsurf, and VS Code with environment variables
This guide covers IDE integration, environment variables, and advanced configuration options.
## IDE Integration
### Configuration File Locations
| IDE | Location |
| ------------------------ | ----------------------------------------------------------------- |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
| Cursor | Settings → MCP → + Add new global MCP server |
### Basic Configuration (uvx)
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_api_token"
}
}
}
}
```
### Docker with Environment File
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "/path/to/your/mcp-atlassian.env",
"ghcr.io/sooperset/mcp-atlassian:latest"
]
}
}
}
```
### Server/Data Center Configuration
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://jira.your-company.com",
"JIRA_PERSONAL_TOKEN": "your_pat",
"JIRA_SSL_VERIFY": "false",
"CONFLUENCE_URL": "https://confluence.your-company.com",
"CONFLUENCE_PERSONAL_TOKEN": "your_pat",
"CONFLUENCE_SSL_VERIFY": "false"
}
}
}
}
```
### Single Service Configuration
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "your_api_token"
}
}
}
}
```
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_api_token"
}
}
}
}
```
## Environment Variables
### Connection Settings
| Variable | Description |
| --------------------------- | -------------------------------------------- |
| `JIRA_URL` | Jira instance URL |
| `JIRA_USERNAME` | Jira username (email for Cloud) |
| `JIRA_API_TOKEN` | Jira API token (Cloud) |
| `JIRA_PERSONAL_TOKEN` | Jira Personal Access Token (Server/DC) |
| `JIRA_SSL_VERIFY` | SSL verification (`true`/`false`) |
| `CONFLUENCE_URL` | Confluence instance URL |
| `CONFLUENCE_USERNAME` | Confluence username (email for Cloud) |
| `CONFLUENCE_API_TOKEN` | Confluence API token (Cloud) |
| `CONFLUENCE_PERSONAL_TOKEN` | Confluence Personal Access Token (Server/DC) |
| `CONFLUENCE_SSL_VERIFY` | SSL verification (`true`/`false`) |
### Filtering Options
| Variable | Description | Example |
| -------------------------- | ----------------------------------- | ---------------------------------- |
| `JIRA_PROJECTS_FILTER` | Limit to specific Jira projects | `PROJ,DEV,SUPPORT` |
| `CONFLUENCE_SPACES_FILTER` | Limit to specific Confluence spaces | `DEV,TEAM,DOC` |
| `ENABLED_TOOLS` | Enable only specific tools | `confluence_search,jira_get_issue` |
### Server Options
| Variable | Description |
| -------------------- | ---------------------------------------------------------- |
| `TRANSPORT` | Transport type (`stdio`, `sse`, `streamable-http`) |
| `STATELESS` | Enable stateless mode for streamable-http (`true`/`false`) |
| `PORT` | Port for HTTP transports (default: `8000`) |
| `HOST` | Host for HTTP transports (default: `0.0.0.0`) |
| `READ_ONLY_MODE` | Disable write operations (`true`/`false`) |
| `MCP_VERBOSE` | Enable verbose logging (`true`/`false`) |
| `MCP_VERY_VERBOSE` | Enable debug logging (`true`/`false`) |
| `MCP_LOGGING_STDOUT` | Log to stdout instead of stderr (`true`/`false`) |
See [.env.example](https://github.com/sooperset/mcp-atlassian/blob/main/.env.example) for all available options.
## Proxy Configuration
MCP Atlassian supports routing API requests through HTTP/HTTPS/SOCKS proxies.
| Variable | Description |
| ------------------------ | ------------------------------- |
| `HTTP_PROXY` | HTTP proxy URL |
| `HTTPS_PROXY` | HTTPS proxy URL |
| `SOCKS_PROXY` | SOCKS proxy URL |
| `NO_PROXY` | Hosts to bypass proxy |
| `JIRA_HTTPS_PROXY` | Jira-specific HTTPS proxy |
| `CONFLUENCE_HTTPS_PROXY` | Confluence-specific HTTPS proxy |
Service-specific variables override global ones.
## Custom HTTP Headers
Add custom HTTP headers to all API requests. Useful in corporate environments.
| Variable | Description |
| --------------------------- | -------------------------------------- |
| `JIRA_CUSTOM_HEADERS` | Custom headers for Jira requests |
| `CONFLUENCE_CUSTOM_HEADERS` | Custom headers for Confluence requests |
**Format:** Comma-separated `key=value` pairs.
```bash theme={null}
JIRA_CUSTOM_HEADERS=X-Forwarded-User=service-account,X-Custom-Auth=token
CONFLUENCE_CUSTOM_HEADERS=X-Service=mcp-integration,X-ALB-Token=secret
```
Header values are masked in debug logs for security.
## Tool Filtering
Control which tools are available:
```bash theme={null}
# Enable specific tools
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
# Read-only mode (disables all write operations)
READ_ONLY_MODE=true
```
Command-line alternative:
```bash theme={null}
uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue"
```
# Common Workflows
Source: https://mcp-atlassian.soomiles.com/docs/guides/common-workflows
Practical recipes for common Jira and Confluence tasks with MCP Atlassian
This guide provides step-by-step workflows for common tasks using MCP Atlassian tools.
## Jira Workflows
### Triage New Issues
1. **Find untriaged issues:**
```json theme={null}
jira_search: {"jql": "project = PROJ AND status = 'Open' AND assignee IS EMPTY ORDER BY created DESC", "limit": 20}
```
2. **Review each issue** to understand the problem:
```json theme={null}
jira_get_issue: {"issue_key": "PROJ-123", "comment_limit": 5}
```
3. **Assign and prioritize:**
```json theme={null}
jira_update_issue: {"issue_key": "PROJ-123", "additional_fields": "{\"assignee\": {\"accountId\": \"user-id\"}, \"priority\": {\"name\": \"High\"}}"}
```
4. **Add a triage comment:**
```json theme={null}
jira_add_comment: {"issue_key": "PROJ-123", "comment": "Triaged: High priority, assigned to backend team."}
```
### Sprint Planning
1. **Get the board and active sprint:**
```json theme={null}
jira_get_agile_boards: {"project_key": "PROJ", "board_type": "scrum"}
```
```json theme={null}
jira_get_sprints_from_board: {"board_id": "42", "state": "active,future"}
```
2. **Review current sprint progress:**
```json theme={null}
jira_get_sprint_issues: {"sprint_id": "100", "fields": "summary,status,story_points,assignee"}
```
3. **Find backlog items for next sprint:**
```json theme={null}
jira_search: {"jql": "project = PROJ AND sprint IS EMPTY AND status = 'Open' ORDER BY priority DESC, created ASC", "limit": 30}
```
### Bulk Issue Creation
Create multiple related issues at once:
```json theme={null}
jira_batch_create_issues: {
"project_key": "PROJ",
"issues": [
{"issue_type": "Task", "summary": "Set up CI pipeline", "description": "Configure GitHub Actions"},
{"issue_type": "Task", "summary": "Write unit tests", "description": "Add tests for core module"},
{"issue_type": "Task", "summary": "Update documentation", "description": "Document new API endpoints"}
]
}
```
### Track Issue Changes
Monitor what changed across multiple issues:
```json theme={null}
jira_batch_get_changelogs: {"issue_keys": ["PROJ-1", "PROJ-2", "PROJ-3"]}
```
Changelog tracking is only available on Jira Cloud.
## Confluence Workflows
### Create Documentation Structure
1. **Create a parent page:**
```json theme={null}
confluence_create_page: {"space_key": "DEV", "title": "Project Documentation", "content": "## Overview\n\nThis space contains all project docs."}
```
2. **Create child pages:**
```json theme={null}
confluence_create_page: {"space_key": "DEV", "title": "API Reference", "content": "## API Endpoints\n\n...", "parent_id": "12345678"}
```
3. **Add labels for organization:**
```json theme={null}
confluence_add_label: {"page_id": "12345678", "label": "api-docs"}
```
### Content Migration
1. **Search for pages to migrate:**
```json theme={null}
confluence_search: {"query": "space = OLD_SPACE AND label = 'migrate' ORDER BY title ASC"}
```
2. **Read each page's content:**
```json theme={null}
confluence_get_page: {"page_id": "12345678", "include_metadata": true}
```
3. **Create in new space:**
```json theme={null}
confluence_create_page: {"space_key": "NEW_SPACE", "title": "Migrated Page", "content": "...migrated content..."}
```
### Identify Stale Content
Find pages that haven't been updated recently:
```json theme={null}
confluence_search: {"query": "space = DEV AND type = page AND lastModified < '2024-01-01' ORDER BY lastModified ASC", "limit": 50}
```
Check page view analytics:
```json theme={null}
confluence_get_page_views: {"page_id": "12345678"}
```
## Cross-Product Workflows
### Link Jira Issues to Confluence Pages
1. **Create a Confluence page with project context:**
```json theme={null}
confluence_create_page: {"space_key": "DEV", "title": "Sprint 42 Retrospective", "content": "## Sprint 42\n\nSee PROJ-100 through PROJ-120 for completed work."}
```
2. **Add a remote link from Jira to Confluence:**
```json theme={null}
jira_create_remote_issue_link: {"issue_key": "PROJ-100", "url": "https://your-instance.atlassian.net/wiki/spaces/DEV/pages/12345678", "title": "Sprint 42 Retro"}
```
# CQL Guide
Source: https://mcp-atlassian.soomiles.com/docs/guides/cql-guide
Master Confluence Query Language for searching content with MCP Atlassian
CQL (Confluence Query Language) is used by `confluence_search` to find content. You can also use simple text queries that automatically use `siteSearch`.
## Basic Syntax
CQL queries follow the pattern: `field operator value`
```
type = page AND space = "DEV"
```
## Common Operators
| Operator | Description | Example |
| -------------------- | ----------------- | -------------------------- |
| `=` | Exact match | `type = "page"` |
| `!=` | Not equal | `type != "comment"` |
| `~` | Contains text | `title ~ "meeting notes"` |
| `IN` | Match any in list | `space IN ("DEV", "TEAM")` |
| `>`, `<`, `>=`, `<=` | Comparison | `created >= "2024-01-01"` |
## Common Fields
| Field | Description | Example |
| -------------- | ---------------- | -------------------------------------- |
| `type` | Content type | `type = "page"` or `type = "blogpost"` |
| `space` | Space key | `space = "DEV"` |
| `title` | Page title | `title ~ "architecture"` |
| `text` | Full text search | `text ~ "API documentation"` |
| `label` | Content label | `label = "approved"` |
| `creator` | Created by | `creator = "john.doe"` |
| `created` | Creation date | `created >= "2024-01-01"` |
| `lastModified` | Last modified | `lastModified >= "2024-06-01"` |
| `ancestor` | Parent page ID | `ancestor = "12345678"` |
| `parent` | Direct parent ID | `parent = "12345678"` |
## Search Types
### CQL Query
Pass a CQL string directly:
```
type=page AND space=DEV AND title~"Meeting Notes"
```
### Simple Text Search
Pass plain text — `confluence_search` auto-detects and uses `siteSearch`:
```
project documentation architecture
```
## Practical Patterns
### Pages in a Space
```
type = page AND space = "DEV" ORDER BY lastModified DESC
```
### Recently Modified Content
```
type = page AND lastModified >= "2024-06-01" ORDER BY lastModified DESC
```
### Content with Specific Label
```
type = page AND label = "architecture" ORDER BY title ASC
```
### Personal Space Search
```
space = "~username" AND type = page
```
Personal space keys starting with `~` must be quoted in CQL: `space = "~username"`
### Pages Under a Parent
```
ancestor = "12345678" AND type = page ORDER BY title ASC
```
### Full Text Search in Space
```
space = "DEV" AND text ~ "database migration" ORDER BY lastModified DESC
```
## Tips
For simple searches, just pass plain text to `confluence_search` — it uses `siteSearch` by default, which mimics the Confluence web UI search.
Use `siteSearch` for relevance-ranked results: `siteSearch ~ "important concept"`
CQL syntax can differ slightly between Cloud and Server/DC. Test your queries if migrating between platforms.
# JQL Guide
Source: https://mcp-atlassian.soomiles.com/docs/guides/jql-guide
Master Jira Query Language for powerful issue searches with MCP Atlassian
JQL (Jira Query Language) is the query language used by `jira_search` to find issues. This guide covers the most useful patterns.
## Basic Syntax
JQL queries follow the pattern: `field operator value`
```
project = "PROJ" AND status = "In Progress"
```
## Common Operators
| Operator | Description | Example |
| -------------------- | ----------------- | ----------------------------------- |
| `=` | Exact match | `status = "Done"` |
| `!=` | Not equal | `status != "Closed"` |
| `~` | Contains text | `summary ~ "bug fix"` |
| `!~` | Does not contain | `summary !~ "test"` |
| `IN` | Match any in list | `status IN ("Open", "In Progress")` |
| `NOT IN` | Not in list | `priority NOT IN ("Low", "Lowest")` |
| `IS` | Null check | `assignee IS EMPTY` |
| `IS NOT` | Not null | `assignee IS NOT EMPTY` |
| `>`, `<`, `>=`, `<=` | Comparison | `created >= "2024-01-01"` |
## Common Fields
| Field | Description | Example |
| -------------------- | --------------- | ---------------------------- |
| `project` | Project key | `project = "PROJ"` |
| `status` | Issue status | `status = "In Progress"` |
| `assignee` | Assigned user | `assignee = currentUser()` |
| `reporter` | Issue creator | `reporter = "john.doe"` |
| `priority` | Priority level | `priority = "High"` |
| `type` / `issuetype` | Issue type | `type = "Bug"` |
| `labels` | Issue labels | `labels = "frontend"` |
| `sprint` | Sprint name | `sprint = "Sprint 42"` |
| `created` | Creation date | `created >= "-7d"` |
| `updated` | Last updated | `updated >= "-24h"` |
| `resolved` | Resolution date | `resolved >= startOfMonth()` |
## Useful Functions
| Function | Description | Example |
| ---------------- | ------------------- | ---------------------------- |
| `currentUser()` | Logged-in user | `assignee = currentUser()` |
| `startOfDay()` | Start of today | `created >= startOfDay()` |
| `startOfWeek()` | Start of this week | `updated >= startOfWeek()` |
| `startOfMonth()` | Start of this month | `resolved >= startOfMonth()` |
| `endOfDay()` | End of today | `due <= endOfDay()` |
| `now()` | Current time | `updated >= now("-1h")` |
## Practical Patterns
### My Open Issues
```
assignee = currentUser() AND resolution = EMPTY ORDER BY priority DESC
```
### Sprint Burndown
```
sprint = "Sprint 42" AND status != "Done" ORDER BY rank ASC
```
### Recent Bugs
```
type = "Bug" AND created >= "-7d" ORDER BY created DESC
```
### Unassigned High Priority
```
assignee IS EMPTY AND priority IN ("High", "Highest") ORDER BY created ASC
```
### Issues Updated Today
```
updated >= startOfDay() AND project = "PROJ" ORDER BY updated DESC
```
### Overdue Issues
```
due < now() AND resolution = EMPTY ORDER BY due ASC
```
### Cross-Project Search
```
project IN ("PROJ", "DEVOPS", "INFRA") AND status = "In Progress"
```
### Text Search Across Fields
```
text ~ "database migration" ORDER BY relevance DESC
```
## Tips
Always include `ORDER BY` in your queries for deterministic, predictable results.
Use relative dates (`"-7d"`, `"-1w"`, `"-1M"`) instead of absolute dates for reusable queries.
Some JQL functions like `issueHistory()` are Cloud-only. Check your Jira version's documentation for supported functions.
# HTTP Transport
Source: https://mcp-atlassian.soomiles.com/docs/http-transport
Deploy MCP Atlassian as an HTTP service with SSE or streamable-http for multi-user and remote scenarios
Instead of using `stdio`, you can run the server as a persistent HTTP service. This enables multi-user scenarios and remote deployment.
## Transport Types
| Transport | Endpoint | Use Case |
| ----------------- | -------- | -------------------------------------- |
| `sse` | `/sse` | Server-Sent Events, good for streaming |
| `streamable-http` | `/mcp` | HTTP-based, good for multi-user |
## Stateless Mode
For Kubernetes deployments or environments where session state should be ephemeral, use the `--stateless` flag with streamable-http transport:
```bash theme={null}
# Using uvx
uvx mcp-atlassian --transport streamable-http --stateless --port 9000 -vv
# Or using Docker
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/sooperset/mcp-atlassian:latest \
--transport streamable-http --stateless --port 9000 -vv
# Or via environment variable
STATELESS=true uvx mcp-atlassian --transport streamable-http --port 9000
```
The `--stateless` flag is only supported with `streamable-http` transport. Using it with `stdio` or `sse` will result in an error.
## Basic Setup
```bash theme={null}
# Using uvx
uvx mcp-atlassian --transport sse --port 9000 -vv
# Or using Docker
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/sooperset/mcp-atlassian:latest \
--transport sse --port 9000 -vv
```
**IDE Configuration:**
```json theme={null}
{
"mcpServers": {
"mcp-atlassian-http": {
"url": "http://localhost:9000/sse"
}
}
}
```
```bash theme={null}
# Using uvx
uvx mcp-atlassian --transport streamable-http --port 9000 -vv
# Or using Docker
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/sooperset/mcp-atlassian:latest \
--transport streamable-http --port 9000 -vv
```
**IDE Configuration:**
```json theme={null}
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp"
}
}
}
```
## Multi-User Authentication
Both transport types support per-request authentication where each user provides their own credentials.
### Authentication Methods
```json theme={null}
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
```json theme={null}
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Token "
}
}
}
}
```
### Server Setup for Multi-User
```bash theme={null}
# Using uvx
uvx mcp-atlassian --oauth-setup -v
# Or using Docker
docker run --rm -i \
-p 8080:8080 \
-v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
```
```bash theme={null}
# Using uvx (with env vars set)
uvx mcp-atlassian --transport streamable-http --port 9000 -vv
# Or using Docker
docker run --rm -p 9000:9000 \
--env-file /path/to/your/.env \
ghcr.io/sooperset/mcp-atlassian:latest \
--transport streamable-http --port 9000 -vv
```
```bash theme={null}
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
```
### Multi-Cloud Support
For multi-tenant applications where each user connects to their own Atlassian cloud instance:
1. Enable minimal OAuth mode:
```bash theme={null}
# Using uvx
ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000
# Or using Docker
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 `
* `X-Atlassian-Cloud-Id: `
### Python Example
```python theme={null}
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():
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, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
result = await session.call_tool(
"jira_get_issue",
{"issue_key": "PROJ-123"}
)
print(result)
asyncio.run(main())
```
* The server uses fallback authentication when requests don't include user-specific credentials
* User tokens are isolated per request - no cross-tenant data leakage
* Falls back to global `ATLASSIAN_OAUTH_CLOUD_ID` if header not provided
# MCP Atlassian
Source: https://mcp-atlassian.soomiles.com/docs/index
Connect AI assistants to Jira and Confluence — search, create, update issues and pages via MCP
Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). Supports both Cloud and Server/Data Center deployments.
Get started in 5 minutes with uvx
Set up API tokens, PATs, or OAuth 2.0
Browse all available Jira and Confluence tools
IDE setup and environment variables
## Example Usage
Ask your AI assistant to:
* **"Find issues assigned to me in PROJ project"**
* **"Search Confluence for onboarding docs"**
* **"Create a bug ticket for the login issue"**
* **"Update the status of PROJ-123 to Done"**
## Compatibility
| Product | Deployment | Support |
| ---------- | ------------------ | ------------------ |
| Confluence | Cloud | Fully supported |
| Confluence | Server/Data Center | Supported (v6.0+) |
| Jira | Cloud | Fully supported |
| Jira | Server/Data Center | Supported (v8.14+) |
# Installation
Source: https://mcp-atlassian.soomiles.com/docs/installation
Install and configure MCP Atlassian using uvx, Docker, pip, or from source
MCP Atlassian can be installed using several methods. Choose the one that best fits your workflow.
## uvx (Recommended)
The simplest way to run MCP Atlassian without permanent installation using [uvx](https://docs.astral.sh/uv/guides/tools/):
```bash theme={null}
# Run directly (downloads on first use, cached for subsequent runs)
uvx mcp-atlassian --help
# Run with a specific Python version if needed
uvx --python=3.12 mcp-atlassian --help
```
### IDE Configuration with uvx
Edit your config file:
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"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"
}
}
}
}
```
Open **Settings** → **MCP** → **+ Add new global MCP server**, then use the same JSON configuration.
## Docker
Docker provides an isolated environment and is recommended for production deployments or when you need specific version control.
```bash theme={null}
# Pull the latest image
docker pull ghcr.io/sooperset/mcp-atlassian:latest
# Run with environment variables
docker run --rm -i \
-e JIRA_URL=https://your-company.atlassian.net \
-e JIRA_USERNAME=your.email@company.com \
-e JIRA_API_TOKEN=your_api_token \
ghcr.io/sooperset/mcp-atlassian:latest
```
### IDE Configuration with Docker
```json theme={null}
{
"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",
"ghcr.io/sooperset/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"
}
}
}
}
```
See [Configuration](/docs/configuration) for more Docker options including environment files.
## pip
Install directly with pip for development or when you need the package in your Python environment:
```bash theme={null}
pip install mcp-atlassian
# Run the server
mcp-atlassian --help
```
## uv
If you're using [uv](https://docs.astral.sh/uv/) for package management:
```bash theme={null}
# Add to your project
uv add mcp-atlassian
# Run
uv run mcp-atlassian --help
```
## From Source
For development or contributing:
```bash theme={null}
git clone https://github.com/sooperset/mcp-atlassian.git
cd mcp-atlassian
uv sync --frozen --all-extras --dev
uv run mcp-atlassian --help
```
See [CONTRIBUTING.md](https://github.com/sooperset/mcp-atlassian/blob/main/CONTRIBUTING.md) for development setup details.
# Tools Reference
Source: https://mcp-atlassian.soomiles.com/docs/tools-reference
Overview of all 65 MCP tools for Jira and Confluence — organized by category with quick links
MCP Atlassian provides **65 tools** for interacting with Jira and Confluence. Tools are organized by category below.
## Jira Tools
Create, read, update, delete, and transition issues
Search with JQL, explore fields and options
Boards, sprints, and agile management
Comments, worklogs, changelogs, user profiles
Issue links, epic links, versions, components
Download attachments and render images
Service desk queues and queue issues
ProForma forms, SLA, dates, development info
## Confluence Tools
Create, read, update, delete pages
Search content with CQL, find users
Upload, download, manage attachments
Comments, labels, page analytics
## Tool Access Control
### Enable Specific Tools
Use `ENABLED_TOOLS` environment variable or `--enabled-tools` flag:
```bash theme={null}
# Environment variable
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
# Command line
uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue,jira_search"
```
### Read-Only Mode
Disable all write operations:
```bash theme={null}
READ_ONLY_MODE=true
```
When enabled, only read operations are available regardless of `ENABLED_TOOLS` setting.
# Confluence Attachments
Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-attachments
Upload, download, list, and manage page attachments
### Upload Attachment
Upload an attachment to Confluence content (page or blog post).
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content_id` | `string` | Yes | The ID of the Confluence content (page or blog post) to attach the file to. Page IDs can be found in the page URL or by using the search/get\_page tools. Example: '123456789' |
| `file_path` | `string` | Yes | Full path to the file to upload. Can be absolute (e.g., '/home/user/document.pdf' or 'C:\Users\name\file.docx') or relative to the current working directory (e.g., './uploads/document.pdf'). If a file with the same name already exists, a new version will be created. |
| `comment` | `string` | No | (Optional) A comment describing this attachment or version. Visible in the attachment history. Example: 'Updated Q4 2024 figures' |
| `minor_edit` | `boolean` | No | (Optional) Whether this is a minor edit. If true, watchers are not notified. Default is false. |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "file_path": "/path/to/diagram.png", "comment": "Updated architecture diagram"}
```
Supports any file type. If an attachment with the same name exists, it's updated (new version created).
***
### Upload Multiple Attachments
Upload multiple attachments to Confluence content in a single operation.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content_id` | `string` | Yes | The ID of the Confluence content (page or blog post) to attach files to. Example: '123456789'. If uploading multiple files with the same names, new versions will be created automatically. |
| `file_paths` | `string` | Yes | Comma-separated list of file paths to upload. Can be absolute or relative paths. Examples: './file1.pdf,./file2.png' or 'C:\docs\report.docx,D:\image.jpg'. All files uploaded with same comment/minor\_edit settings. |
| `comment` | `string` | No | (Optional) Comment for all uploaded attachments. Visible in version history. Example: 'Q4 2024 batch upload' |
| `minor_edit` | `boolean` | No | (Optional) Whether this is a minor edit. If true, watchers are not notified. Default is false. |
***
### Get Content Attachments
List all attachments for a Confluence content item (page or blog post).
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content_id` | `string` | Yes | The ID of the Confluence content (page or blog post) to list attachments for. Example: '123456789' |
| `start` | `integer` | No | (Optional) Starting index for pagination. Use 0 for the first page. To get the next page, add the 'limit' value to 'start'. Default: 0 |
| `limit` | `integer` | No | (Optional) Maximum number of attachments to return per request (1-100). Use pagination (start/limit) for large attachment lists. Default: 50 |
| `filename` | `string` | No | (Optional) Filter results to only attachments matching this filename. Exact match only. Example: 'report.pdf' |
| `media_type` | `string` | No | (Optional) Filter by MIME type. **Note**: Confluence API returns 'application/octet-stream' for most binary files (PNG, JPG, PDF) instead of specific MIME types like 'image/png'. For more reliable filtering, use the 'filename' parameter. Examples: 'application/octet-stream' (binary files), 'application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' (for .docx) |
| **Example:** | | | |
```json theme={null}
{"content_id": "12345678", "media_type": "application/octet-stream"}
```
Use `media_type="application/octet-stream"` for binary files (Confluence returns this for most files including images). Use `filename` parameter for specific files.
Confluence API returns generic MIME types — use the `mediaTypeDescription` field for human-readable type info.
***
### Download Attachment
Download an attachment from Confluence as an embedded resource.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attachment_id` | `string` | Yes | The ID of the attachment to download (e.g., 'att123456789'). Find attachment IDs using get\_attachments tool. Example workflow: get\_attachments(content\_id) → use returned ID here. |
***
### Download All Content Attachments
Download all attachments for a Confluence content item as embedded resources.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `content_id` | `string` | Yes | The ID of the Confluence content (page or blog post) to download attachments from. Example: '123456789' |
***
### Delete Attachment
Permanently delete an attachment from Confluence.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attachment_id` | `string` | Yes | The ID of the attachment to delete. Attachment IDs can be found using the get\_attachments tool. Example: 'att123456789'. **Warning**: This permanently deletes the attachment and all its versions. |
***
### Get Page Images
Get all images attached to a Confluence page as inline image content.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | ---------------------------------------------------------------------------------------- |
| `content_id` | `string` | Yes | The ID of the Confluence page or blog post to retrieve images from. Example: '123456789' |
***
# Confluence Comments & Labels
Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments
Comments, labels, and page analytics
### Add Comment
Add a comment to a Confluence page.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | -------------------------------------- |
| `page_id` | `string` | Yes | The ID of the page to add a comment to |
| `content` | `string` | Yes | The comment content in Markdown format |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "body": "Great documentation! Consider adding examples for the API section."}
```
Supports Markdown formatting. Comments are added to the page's comment section.
***
### Get Comments
Get comments for a specific Confluence page.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | `string` | Yes | Confluence page ID (numeric ID, can be parsed from URL, e.g. from '[https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title](https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title)' -> '123456789') |
***
### Get Labels
Get labels for Confluence content (pages, blog posts, or attachments).
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page_id` | `string` | Yes | Confluence content ID (page, blog post, or attachment). For pages: numeric ID from URL (e.g., '123456789'). For attachments: ID with 'att' prefix (e.g., 'att123456789'). Works with any Confluence content type that supports labels. |
***
### Add Label
Add label to Confluence content (pages, blog posts, or attachments).
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page_id` | `string` | Yes | Confluence content ID to label. For pages/blogs: numeric ID (e.g., '123456789'). For attachments: ID with 'att' prefix (e.g., 'att123456789'). Use get\_attachments to find attachment IDs. |
| `name` | `string` | Yes | Label name to add (lowercase, no spaces). Examples: 'draft', 'reviewed', 'confidential', 'v1.0'. Labels help organize and categorize content. |
***
### Get Page Views
Get view statistics for a Confluence page.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page_id` | `string` | Yes | Confluence page ID (numeric ID, can be found in the page URL). For example, in '[https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title](https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title)', the page ID is '123456789'. |
| `include_title` | `boolean` | No | Whether to fetch and include the page title |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "period": "lastMonth"}
```
Useful for identifying popular or stale content. Available periods depend on your Confluence analytics configuration.
Analytics features may require additional permissions on Server/DC.
***
# Confluence Pages
Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages
Create, read, update, delete pages, and navigate page trees
### Get Page
Get content of a specific Confluence page by its ID, or by its title and space key.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | `string` | No | Confluence page ID (numeric ID, can be found in the page URL). For example, in the URL '[https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title](https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title)', the page ID is '123456789'. Provide this OR both 'title' and 'space\_key'. If page\_id is provided, title and space\_key will be ignored. |
| `title` | `string` | No | The exact title of the Confluence page. Use this with 'space\_key' if 'page\_id' is not known. |
| `space_key` | `string` | No | The key of the Confluence space where the page resides (e.g., 'DEV', 'TEAM'). Required if using 'title'. |
| `include_metadata` | `boolean` | No | Whether to include page metadata such as creation date, last update, version, and labels. |
| `convert_to_markdown` | `boolean` | No | Whether to convert page to markdown (true) or keep it in raw HTML format (false). Raw HTML can reveal macros (like dates) not visible in markdown, but CAUTION: using HTML significantly increases token usage in AI responses. |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "include_metadata": true}
```
Content is returned in Markdown format (auto-converted from Confluence storage format). Use `include_metadata` for labels, version info, and last modified date.
***
### Create Page
Create a new Confluence page.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `space_key` | `string` | Yes | The key of the space to create the page in (usually a short uppercase code like 'DEV', 'TEAM', or 'DOC') |
| `title` | `string` | Yes | The title of the page |
| `content` | `string` | Yes | The content of the page. Format depends on content\_format parameter. Can be Markdown (default), wiki markup, or storage format |
| `parent_id` | `string` | No | (Optional) parent page ID. If provided, this page will be created as a child of the specified page |
| `content_format` | `string` | No | (Optional) The format of the content parameter. Options: 'markdown' (default), 'wiki', or 'storage'. Wiki format uses Confluence wiki markup syntax |
| `enable_heading_anchors` | `boolean` | No | (Optional) Whether to enable automatic heading anchor generation. Only applies when content\_format is 'markdown' |
| `emoji` | `string` | No | (Optional) Page title emoji (icon shown in navigation). Can be any emoji character like '📝', '🚀', '📚'. Set to null/None to remove. |
| **Example:** | | | |
```json theme={null}
{"space_key": "DEV", "title": "Architecture Decision Record", "content": "## Context\n\nWe need to decide...", "parent_id": "98765432"}
```
Use Markdown for content — it's auto-converted to Confluence storage format. Specify `parent_id` to create as a child page.
***
### Update Page
Update an existing Confluence page.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page_id` | `string` | Yes | The ID of the page to update |
| `title` | `string` | Yes | The new title of the page |
| `content` | `string` | Yes | The new content of the page. Format depends on content\_format parameter |
| `is_minor_edit` | `boolean` | No | Whether this is a minor edit |
| `version_comment` | `string` | No | Optional comment for this version |
| `parent_id` | `string` | No | Optional the new parent page ID |
| `content_format` | `string` | No | (Optional) The format of the content parameter. Options: 'markdown' (default), 'wiki', or 'storage'. Wiki format uses Confluence wiki markup syntax |
| `enable_heading_anchors` | `boolean` | No | (Optional) Whether to enable automatic heading anchor generation. Only applies when content\_format is 'markdown' |
| `emoji` | `string` | No | (Optional) Page title emoji (icon shown in navigation). Can be any emoji character like '📝', '🚀', '📚'. Set to null/None to remove. |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "title": "Updated Title", "content": "## Updated Content\n\nNew information...", "is_minor_edit": true}
```
Set `is_minor_edit: true` to skip notification emails. The page version is auto-incremented.
***
### Delete Page
Delete an existing Confluence page.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ---------------------------- |
| `page_id` | `string` | Yes | The ID of the page to delete |
***
### Get Page Children
Get child pages and folders of a specific Confluence page.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `parent_id` | `string` | Yes | The ID of the parent page whose children you want to retrieve |
| `expand` | `string` | No | Fields to expand in the response (e.g., 'version', 'body.storage') |
| `limit` | `integer` | No | Maximum number of child items to return (1-50) |
| `include_content` | `boolean` | No | Whether to include the page content in the response |
| `convert_to_markdown` | `boolean` | No | Whether to convert page content to markdown (true) or keep it in raw HTML format (false). Only relevant if include\_content is true. |
| `start` | `integer` | No | Starting index for pagination (0-based) |
| `include_folders` | `boolean` | No | Whether to include child folders in addition to child pages |
***
### Get Page History
Get a historical version of a specific Confluence page.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page_id` | `string` | Yes | Confluence page ID (numeric ID, can be found in the page URL). For example, in '[https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title](https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title)', the page ID is '123456789'. |
| `version` | `integer` | Yes | The version number of the page to retrieve |
| `convert_to_markdown` | `boolean` | No | Whether to convert page to markdown (true) or keep it in raw HTML format (false). Raw HTML can reveal macros (like dates) not visible in markdown, but CAUTION: using HTML significantly increases token usage in AI responses. |
***
# Confluence Search
Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-search
Search content with CQL and find users
### Search Content
Search Confluence content using simple terms or CQL.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | `string` | Yes | Search query - can be either a simple text (e.g. 'project documentation') or a CQL query string. Simple queries use 'siteSearch' by default, to mimic the WebUI search, with an automatic fallback to 'text' search if not supported. Examples of CQL: - Basic search: 'type=page AND space=DEV' - Personal space search: 'space="~~username"' (note: personal space keys starting with \~ must be quoted) - Search by title: 'title~~"Meeting Notes"' - Use siteSearch: 'siteSearch \~ "important concept"' - Use text search: 'text \~ "important concept"' - Recent content: 'created >= "2023-01-01"' - Content with specific label: 'label=documentation' - Recently modified content: 'lastModified > startOfMonth("-1M")' - Content modified this year: 'creator = currentUser() AND lastModified > startOfYear()' - Content you contributed to recently: 'contributor = currentUser() AND lastModified > startOfWeek()' - Content watched by user: 'watcher = "[user@domain.com](mailto:user@domain.com)" AND type = page' - Exact phrase in content: 'text \~ ""Urgent Review Required"" AND label = "pending-approval"' - Title wildcards: 'title \~ "Minutes\*" AND (space = "HR" OR space = "Marketing")' Note: Special identifiers need proper quoting in CQL: personal space keys (e.g., "\~username"), reserved words, numeric IDs, and identifiers with special characters. |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| `spaces_filter` | `string` | No | (Optional) Comma-separated list of space keys to filter results by. Overrides the environment variable CONFLUENCE\_SPACES\_FILTER if provided. Use empty string to disable filtering. |
| **Example:** | | | |
```json theme={null}
{"query": "type=page AND space=DEV AND title~'Architecture'", "limit": 10}
```
Supports both CQL queries and simple text search. Simple text uses `siteSearch` by default with automatic fallback to `text` search.
CQL syntax may differ slightly between Cloud and Server/DC. Personal spaces use `space="~username"` (quoted).
***
### Search User
Search Confluence users using CQL.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | `string` | Yes | Search query - a CQL query string for user search. Examples of CQL: - Basic user lookup by full name: 'user.fullname \~ "First Last"' Note: Special identifiers need proper quoting in CQL: personal space keys (e.g., "\~username"), reserved words, numeric IDs, and identifiers with special characters. |
| `limit` | `integer` | No | Maximum number of results (1-50) |
***
# Jira Agile
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-agile
Boards, sprints, and agile project management
### Get Agile Boards
Get jira agile boards by name, project key, or type.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | ----------------------------------------------------------- |
| `board_name` | `string` | No | (Optional) The name of board, support fuzzy search |
| `project_key` | `string` | No | (Optional) Jira project key (e.g., 'PROJ', 'ACV2') |
| `board_type` | `string` | No | (Optional) The type of jira board (e.g., 'scrum', 'kanban') |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| **Example:** | | | |
```json theme={null}
{"board_name": "Sprint Board", "project_key": "PROJ", "board_type": "scrum"}
```
Supports fuzzy search by board name. Combine with `project_key` to narrow results.
***
### Get Board Issues
Get all issues linked to a specific board filtered by JQL.
**Parameters:**
| Parameter | Type | Required | Description |
| ---------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `board_id` | `string` | Yes | The id of the board (e.g., '1001') |
| `jql` | `string` | Yes | JQL query string (Jira Query Language). Examples: - Find Epics: "issuetype = Epic AND project = PROJ" - Find issues in Epic: "parent = PROJ-123" - Find by status: "status = 'In Progress' AND project = PROJ" - Find by assignee: "assignee = currentUser()" - Find recently updated: "updated >= -7d AND project = PROJ" - Find by label: "labels = frontend AND project = PROJ" - Find by priority: "priority = High AND project = PROJ" |
| `fields` | `string` | No | Comma-separated fields to return in the results. Use '\*all' for all fields, or specify individual fields like 'summary,status,assignee,priority' |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| `expand` | `string` | No | Optional fields to expand in the response (e.g., 'changelog'). |
***
### Get Sprints from Board
Get jira sprints from board by state.
**Parameters:**
| Parameter | Type | Required | Description |
| ---------- | --------- | -------- | ------------------------------------------------- |
| `board_id` | `string` | Yes | The id of board (e.g., '1000') |
| `state` | `string` | No | Sprint state (e.g., 'active', 'future', 'closed') |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `limit` | `integer` | No | Maximum number of results (1-50) |
***
### Get Sprint Issues
Get jira issues from sprint.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sprint_id` | `string` | Yes | The id of sprint (e.g., '10001') |
| `fields` | `string` | No | Comma-separated fields to return in the results. Use '\*all' for all fields, or specify individual fields like 'summary,status,assignee,priority' |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| **Example:** | | | |
```json theme={null}
{"sprint_id": "42", "fields": "summary,status,assignee,story_points"}
```
Get the sprint ID from `jira_get_sprints_from_board` first.
***
### Create Sprint
Create Jira sprint for a board.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | --------------------------------------- |
| `board_id` | `string` | Yes | The id of board (e.g., '1000') |
| `sprint_name` | `string` | Yes | Name of the sprint (e.g., 'Sprint 1') |
| `start_date` | `string` | Yes | Start time for sprint (ISO 8601 format) |
| `end_date` | `string` | Yes | End time for sprint (ISO 8601 format) |
| `goal` | `string` | No | (Optional) Goal of the sprint |
***
### Update Sprint
Update jira sprint.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ------------------------------------------------------------ |
| `sprint_id` | `string` | Yes | The id of sprint (e.g., '10001') |
| `sprint_name` | `string` | No | (Optional) New name for the sprint |
| `state` | `string` | No | (Optional) New state for the sprint (future\|active\|closed) |
| `start_date` | `string` | No | (Optional) New start date for the sprint |
| `end_date` | `string` | No | (Optional) New end date for the sprint |
| `goal` | `string` | No | (Optional) New goal for the sprint |
***
# Jira Attachments
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-attachments
Download attachments and render issue images
### Download Attachments
Download attachments from a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | --------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123"}
```
Downloads all attachments from the issue. Files larger than 50MB are skipped. Returns base64-encoded content.
***
### Get Issue Images
Get all images attached to a Jira issue as inline image content.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123'). Returns image attachments as inline ImageContent for LLM vision. |
***
# Jira Comments & Worklogs
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-comments-worklogs
Comments, worklogs, changelogs, and user profiles
### Add Comment
Add a comment to a Jira issue.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `comment` | `string` | Yes | Comment text in Markdown format |
| `visibility` | `string` | No | (Optional) Comment visibility as JSON string (e.g. `'{"type":"group","value":"jira-users"}'`) |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "comment": "## Investigation\n\nFound the root cause in module X."}
```
Supports Markdown formatting. Use `visibility` parameter for restricted comments (e.g., service desk internal notes).
***
### Edit Comment
Edit an existing comment on a Jira issue.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `comment_id` | `string` | Yes | The ID of the comment to edit |
| `comment` | `string` | Yes | Updated comment text in Markdown format |
| `visibility` | `string` | No | (Optional) Comment visibility as JSON string (e.g. `'{"type":"group","value":"jira-users"}'`) |
***
### Get Worklog
Get worklog entries for a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
***
### Add Worklog
Add a worklog entry to a Jira issue.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `time_spent` | `string` | Yes | Time spent in Jira format. Examples: '1h 30m' (1 hour and 30 minutes), '1d' (1 day), '30m' (30 minutes), '4h' (4 hours) |
| `comment` | `string` | No | (Optional) Comment for the worklog in Markdown format |
| `started` | `string` | No | (Optional) Start time in ISO format. If not provided, the current time will be used. Example: '2023-08-01T12:00:00.000+0000' |
| `original_estimate` | `string` | No | (Optional) New value for the original estimate |
| `remaining_estimate` | `string` | No | (Optional) New value for the remaining estimate |
***
### Batch Get Changelogs
Get changelogs for multiple Jira issues (Cloud only).
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_ids_or_keys` | `string` | Yes | Comma-separated list of Jira issue IDs or keys (e.g. 'PROJ-123,PROJ-124') |
| `fields` | `string` | No | (Optional) Comma-separated list of fields to filter changelogs by (e.g. 'status,assignee'). Default to None for all fields. |
| `limit` | `integer` | No | Maximum number of changelogs to return in result for each issue. Default to -1 for all changelogs. Notice that it only limits the results in the response, the function will still fetch all the data. |
| **Example:** | | | |
```json theme={null}
{"issue_keys": ["PROJ-1", "PROJ-2", "PROJ-3"]}
```
Efficient for tracking field changes across multiple issues at once. Returns change history for each issue.
Only available on Jira Cloud.
***
### Get User Profile
Retrieve profile information for a specific Jira user.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_identifier` | `string` | Yes | Identifier for the user (e.g., email address '[user@example.com](mailto:user@example.com)', username 'johndoe', account ID 'accountid:...', or key for Server/DC). |
***
# Jira Forms & Metrics
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-forms-metrics
ProForma forms, SLA metrics, dates, and development info
### Get Issue Forms
Get all ProForma forms associated with a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123') |
***
### Get Form Details
Get detailed information about a specific ProForma form.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | ----------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123') |
| `form_id` | `string` | Yes | ProForma form UUID (e.g., '1946b8b7-8f03-4dc0-ac2d-5fac0d960c6a') |
***
### Update Form Answers
Update form field answers using the Jira Forms REST API.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123') |
| `form_id` | `string` | Yes | ProForma form UUID (e.g., '1946b8b7-8f03-4dc0-ac2d-5fac0d960c6a') |
| `answers` | `array` | Yes | List of answer objects. Each answer must have: questionId (string), type (TEXT/NUMBER/SELECT/etc), value (any) |
***
### Get Issue Dates
Get date information and status transition history for a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------------ | --------- | -------- | ----------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `include_status_changes` | `boolean` | No | Include status change history with timestamps and durations |
| `include_status_summary` | `boolean` | No | Include aggregated time spent in each status |
***
### Get Issue SLA
Calculate SLA metrics for a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `metrics` | `string` | No | Comma-separated list of SLA metrics to calculate. Available: cycle\_time, lead\_time, time\_in\_status, due\_date\_compliance, resolution\_time, first\_response\_time. Defaults to configured metrics or 'cycle\_time,time\_in\_status'. |
| `working_hours_only` | `boolean` | No | Calculate using working hours only (excludes weekends/non-business hours). Defaults to value from JIRA\_SLA\_WORKING\_HOURS\_ONLY environment variable. |
| `include_raw_dates` | `boolean` | No | Include raw date values in the response |
| **Example:** | | | |
```json theme={null}
{"issue_key": "SD-456", "metrics": "cycle_time,time_in_status"}
```
Configure SLA calculation via `JIRA_SLA_*` environment variables. Set `JIRA_SLA_WORKING_HOURS_ONLY=true` for business hours only.
***
### Get Issue Development Info
Get development information (PRs, commits, branches) linked to a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123') |
| `application_type` | `string` | No | (Optional) Filter by application type. Examples: 'stash' (Bitbucket Server), 'bitbucket', 'github', 'gitlab' |
| `data_type` | `string` | No | (Optional) Filter by data type. Examples: 'pullrequest', 'branch', 'repository' |
***
### Get Issues Development Info
Get development information for multiple Jira issues.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `issue_keys` | `string` | Yes | Comma-separated list of Jira issue keys (e.g., 'PROJ-123,PROJ-456') |
| `application_type` | `string` | No | (Optional) Filter by application type. Examples: 'stash' (Bitbucket Server), 'bitbucket', 'github', 'gitlab' |
| `data_type` | `string` | No | (Optional) Filter by data type. Examples: 'pullrequest', 'branch', 'repository' |
***
# Jira Issues
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues
Create, read, update, delete, and transition Jira issues
### Get Issue
Get details of a specific Jira issue including its Epic links and relationship information.
**Parameters:**
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `fields` | `string` | No | (Optional) Comma-separated list of fields to return (e.g., 'summary,status,customfield\_10010'). You may also provide a single field as a string (e.g., 'duedate'). Use '\*all' for all fields (including custom fields), or omit for essential fields only. |
| `expand` | `string` | No | (Optional) Fields to expand. Examples: 'renderedFields' (for rendered content), 'transitions' (for available status transitions), 'changelog' (for history) |
| `comment_limit` | `integer` | No | Maximum number of comments to include (0 or null for no comments) |
| `properties` | `string` | No | (Optional) A comma-separated list of issue properties to return |
| `update_history` | `boolean` | No | Whether to update the issue view history for the requesting user |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "fields": "summary,status,assignee", "comment_limit": 5}
```
Use `fields: "*all"` to get all fields including custom ones. Use `expand: "renderedFields"` for rendered HTML content.
Custom field IDs differ between Cloud and Server/DC. Use `jira_search_fields` to discover field IDs.
***
### Create Issue
Create a new Jira issue with optional Epic link or parent for subtasks.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_key` | `string` | Yes | The JIRA project key (e.g. 'PROJ', 'DEV', 'ACV2'). This is the prefix of issue keys in your project. Never assume what it might be, always ask the user. |
| `summary` | `string` | Yes | Summary/title of the issue |
| `issue_type` | `string` | Yes | Issue type (e.g. 'Task', 'Bug', 'Story', 'Epic', 'Subtask'). The available types depend on your project configuration. For subtasks, use 'Subtask' (not 'Sub-task') and include parent in additional\_fields. |
| `assignee` | `string` | No | (Optional) Assignee's user identifier (string): Email, display name, or account ID (e.g., '[user@example.com](mailto:user@example.com)', 'John Doe', 'accountid:...') |
| `description` | `string` | No | Issue description in Markdown format |
| `components` | `string` | No | (Optional) Comma-separated list of component names to assign (e.g., 'Frontend,API') |
| `additional_fields` | `string` | No | (Optional) JSON string of additional fields to set. Examples: - Set priority: `{"priority": {"name": "High"}}` - Add labels: `{"labels": ["frontend", "urgent"]}` - Link to parent (for any issue type): `{"parent": "PROJ-123"}` - Link to epic: `{"epicKey": "EPIC-123"}` or `{"epic_link": "EPIC-123"}` - Set Fix Version/s: `{"fixVersions": [{"id": "10020"}]}` - Custom fields: `{"customfield_10010": "value"}` |
| **Example:** | | | |
```json theme={null}
{"project_key": "PROJ", "issue_type": "Task", "summary": "Implement new feature", "description": "## Requirements\n\n- Feature A\n- Feature B"}
```
Use Markdown in the description — it's automatically converted to ADF (Cloud) or wiki markup (Server/DC). For epics, provide `epic_name` parameter.
Cloud uses ADF format internally (auto-converted from Markdown). Server/DC uses wiki markup.
***
### Update Issue
Update an existing Jira issue including changing status, adding Epic links, updating fields, etc.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `fields` | `string` | Yes | JSON string of fields to update. For 'assignee', provide a string identifier (email, name, or accountId). For 'description', provide text in Markdown format. Example: `'{"assignee": "user@example.com", "summary": "New Summary", "description": "## Updated\nMarkdown text"}'` |
| `additional_fields` | `string` | No | (Optional) JSON string of additional fields to update. Use this for custom fields or more complex updates. Link to epic: `{"epicKey": "EPIC-123"}` or `{"epic_link": "EPIC-123"}`. |
| `components` | `string` | No | (Optional) Comma-separated list of component names (e.g., 'Frontend,API') |
| `attachments` | `string` | No | (Optional) JSON string array or comma-separated list of file paths to attach to the issue. Example: '/path/to/file1.txt,/path/to/file2.txt' or \['/path/to/file1.txt','/path/to/file2.txt'] |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "summary": "Updated title", "description": "New description", "additional_fields": "{\"priority\": {\"name\": \"High\"}}"}
```
Use `additional_fields` as a JSON string for any field not covered by explicit parameters. Find field IDs with `jira_search_fields`.
***
### Delete Issue
Delete an existing Jira issue.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
***
### Batch Create Issues
Create multiple Jira issues in a batch.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issues` | `string` | Yes | JSON array of issue objects. Each object should contain: - project\_key (required): The project key (e.g., 'PROJ') - summary (required): Issue summary/title - issue\_type (required): Type of issue (e.g., 'Task', 'Bug') - description (optional): Issue description in Markdown format - assignee (optional): Assignee username or email - components (optional): Array of component names Example: `[{"project_key": "PROJ", "summary": "Issue 1", "issue_type": "Task"}, {"project_key": "PROJ", "summary": "Issue 2", "issue_type": "Bug", "components": ["Frontend"]}]` |
| `validate_only` | `boolean` | No | If true, only validates the issues without creating them |
***
### Transition Issue
Transition a Jira issue to a new status.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `transition_id` | `string` | Yes | ID of the transition to perform. Use the jira\_get\_transitions tool first to get the available transition IDs for the issue. Example values: '11', '21', '31' |
| `fields` | `string` | No | (Optional) JSON string of fields to update during the transition. Some transitions require specific fields to be set (e.g., resolution). Example: `'{"resolution": {"name": "Fixed"}}'` |
| `comment` | `string` | No | (Optional) Comment to add during the transition in Markdown format. This will be visible in the issue history. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "transition_name": "Done", "comment": "Closing as completed"}
```
Use `jira_get_transitions` first to see available transitions for the current issue state.
***
### Get Transitions
Get available status transitions for a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
***
### Get All Projects
Get all Jira projects accessible to the current user.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------ | --------- | -------- | --------------------------------------------------- |
| `include_archived` | `boolean` | No | Whether to include archived projects in the results |
***
### Get Project Issues
Get all issues for a specific Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | --------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'ACV2') |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
***
# Jira Links & Versions
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-links-versions
Issue links, epic links, remote links, project versions, and components
### Get Link Types
Get all available issue link types.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------------------------------------------- |
| `name_filter` | `string` | No | (Optional) Filter link types by name substring (case-insensitive) |
***
### Create Issue Link
Create a link between two Jira issues.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `link_type` | `string` | Yes | The type of link to create (e.g., 'Duplicate', 'Blocks', 'Relates to') |
| `inward_issue_key` | `string` | Yes | The key of the inward issue (e.g., 'PROJ-123', 'ACV2-642') |
| `outward_issue_key` | `string` | Yes | The key of the outward issue (e.g., 'PROJ-456') |
| `comment` | `string` | No | (Optional) Comment to add to the link |
| `comment_visibility` | `string` | No | (Optional) Visibility settings for the comment as JSON string (e.g. `'{"type":"group","value":"jira-users"}'`) |
***
### Remove Issue Link
Remove a link between two Jira issues.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ---------------------------- |
| `link_id` | `string` | Yes | The ID of the link to remove |
***
### Link to Epic
Link an existing issue to an epic.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | ----------------------------------------------------------- |
| `issue_key` | `string` | Yes | The key of the issue to link (e.g., 'PROJ-123', 'ACV2-642') |
| `epic_key` | `string` | Yes | The key of the epic to link to (e.g., 'PROJ-456') |
***
### Create Remote Issue Link
Create a remote issue link (web link or Confluence link) for a Jira issue.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | The key of the issue to add the link to (e.g., 'PROJ-123', 'ACV2-642') |
| `url` | `string` | Yes | The URL to link to (e.g., '[https://example.com/page](https://example.com/page)' or Confluence page URL) |
| `title` | `string` | Yes | The title/name of the link (e.g., 'Documentation Page', 'Confluence Page') |
| `summary` | `string` | No | (Optional) Description of the link |
| `relationship` | `string` | No | (Optional) Relationship description (e.g., 'causes', 'relates to', 'documentation') |
| `icon_url` | `string` | No | (Optional) URL to a 16x16 icon for the link |
***
### Get Project Versions
Get all fix versions for a specific Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | --------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'ACV2') |
***
### Get Project Components
Get all components for a specific Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | --------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'ACV2') |
***
### Create Version
Create a new fix version in a Jira project.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------- | -------- | -------- | --------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'ACV2') |
| `name` | `string` | Yes | Name of the version |
| `start_date` | `string` | No | Start date (YYYY-MM-DD) |
| `release_date` | `string` | No | Release date (YYYY-MM-DD) |
| `description` | `string` | No | Description of the version |
***
### Batch Create Versions
Batch create multiple versions in a Jira project.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'ACV2') |
| `versions` | `string` | Yes | JSON array of version objects. Each object should contain: - name (required): Name of the version - startDate (optional): Start date (YYYY-MM-DD) - releaseDate (optional): Release date (YYYY-MM-DD) - description (optional): Description of the version Example: `[{"name": "v1.0", "startDate": "2025-01-01", "releaseDate": "2025-02-01", "description": "First release"}, {"name": "v2.0"}]` |
***
# Jira Search & Fields
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields
Search issues with JQL, explore fields and field options
### Search Issues
Search Jira issues using JQL (Jira Query Language).
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jql` | `string` | Yes | JQL query string (Jira Query Language). Examples: - Find Epics: "issuetype = Epic AND project = PROJ" - Find issues in Epic: "parent = PROJ-123" - Find by status: "status = 'In Progress' AND project = PROJ" - Find by assignee: "assignee = currentUser()" - Find recently updated: "updated >= -7d AND project = PROJ" - Find by label: "labels = frontend AND project = PROJ" - Find by priority: "priority = High AND project = PROJ" |
| `fields` | `string` | No | (Optional) Comma-separated fields to return in the results. Use '\*all' for all fields, or specify individual fields like 'summary,status,assignee,priority' |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `projects_filter` | `string` | No | (Optional) Comma-separated list of project keys to filter results by. Overrides the environment variable JIRA\_PROJECTS\_FILTER if provided. |
| `expand` | `string` | No | (Optional) fields to expand. Examples: 'renderedFields', 'transitions', 'changelog' |
| **Example:** | | | |
```json theme={null}
{"jql": "project = PROJ AND status = 'In Progress' ORDER BY updated DESC", "limit": 20}
```
Always use `ORDER BY` for deterministic results. Use `fields` parameter to limit returned data for faster queries.
Some JQL functions (e.g., `issueHistory()`) are Cloud-only.
***
### Search Fields
Search Jira fields by keyword with fuzzy match.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `keyword` | `string` | No | Keyword for fuzzy search. If left empty, lists the first 'limit' available fields in their default order. |
| `limit` | `integer` | No | Maximum number of results |
| `refresh` | `boolean` | No | Whether to force refresh the field list |
| **Example:** | | | |
```json theme={null}
{"keyword": "story points", "issue_type": "Story", "project_key": "PROJ"}
```
Use this to discover custom field IDs before using them in `jira_create_issue` or `jira_update_issue`.
***
### Get Field Options
Get allowed option values for a custom field.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------------------------------------------------------------------- |
| `field_id` | `string` | Yes | Custom field ID (e.g., 'customfield\_10001'). Use jira\_search\_fields to find field IDs. |
| `context_id` | `string` | No | Field context ID (Cloud only). If omitted, auto-resolves to the global context. |
| `project_key` | `string` | No | Project key (required for Server/DC). Example: 'PROJ' |
| `issue_type` | `string` | No | Issue type name (required for Server/DC). Example: 'Bug' |
***
# Jira Service Desk
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-service-desk
Service desk queues and queue issues
### Get Service Desk For Project
Get the Jira Service Desk associated with a project key.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ------------------------------ |
| `project_key` | `string` | Yes | Jira project key (e.g., 'SUP') |
***
### Get Service Desk Queues
Get queues for a Jira Service Desk.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | --------------------------------------- |
| `service_desk_id` | `string` | Yes | Service desk ID (e.g., '4') |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `limit` | `integer` | No | Maximum number of results (1-50) |
***
### Get Queue Issues
Get issues from a Jira Service Desk queue.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | --------------------------------------- |
| `service_desk_id` | `string` | Yes | Service desk ID (e.g., '4') |
| `queue_id` | `string` | Yes | Queue ID (e.g., '47') |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `limit` | `integer` | No | Maximum number of results (1-50) |
***
# Troubleshooting
Source: https://mcp-atlassian.soomiles.com/docs/troubleshooting
Fix auth errors (401/403), field issues, rate limiting, SSL problems, and debug MCP Atlassian connections
## Common Issues
* Ensure you're using API tokens, not your account password
* Verify the token hasn't expired
* Check that `JIRA_USERNAME` / `CONFLUENCE_USERNAME` is your email address
* Verify your Personal Access Token is valid and not expired
* For older Confluence servers, try basic auth with `CONFLUENCE_USERNAME` and `CONFLUENCE_API_TOKEN` (where token is your password)
For Server/Data Center with self-signed certificates:
```bash theme={null}
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
```
Ensure your Atlassian account has sufficient permissions to access the spaces/projects you're targeting.
## Debugging
### Enable Verbose Logging
```bash theme={null}
# Standard verbose
MCP_VERBOSE=true
# Debug level (includes request details)
MCP_VERY_VERBOSE=true
# Log to stdout instead of stderr
MCP_LOGGING_STDOUT=true
```
### View Logs
```bash theme={null}
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
```cmd theme={null}
type %APPDATA%\Claude\logs\mcp*.log | more
```
### MCP Inspector
Test your configuration interactively:
```bash theme={null}
# With uvx
npx @modelcontextprotocol/inspector uvx mcp-atlassian
# With local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-atlassian run mcp-atlassian
```
## Debugging Custom Headers
### Verify Headers Are Applied
1. Enable debug logging:
```bash theme={null}
MCP_VERY_VERBOSE=true
MCP_LOGGING_STDOUT=true
```
2. Check logs for header confirmation:
```
DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}
```
### Correct Header Format
```bash theme={null}
# Correct
JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
# Incorrect (extra quotes)
JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"
# Incorrect (colon instead of equals)
JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2
# Incorrect (spaces around equals)
JIRA_CUSTOM_HEADERS=X-Custom = value1
```
Header values containing sensitive information are automatically masked in logs.
## Authentication Errors
**Cause:** Invalid or expired API token.
**Fix:**
1. Verify your API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Ensure `JIRA_USERNAME` matches the email associated with the token
3. Check that the token hasn't been revoked
```bash theme={null}
# Test your credentials
curl -u "your.email@example.com:your_api_token" \
"https://your-instance.atlassian.net/rest/api/2/myself"
```
**Cause:** Invalid PAT or PAT doesn't have required permissions.
**Fix:**
1. Create a new PAT in your Jira/Confluence profile settings
2. Ensure the PAT has sufficient permissions for the operations you need
3. Note: Server/DC limits PAT count (max 10 per user)
```bash theme={null}
# Test PAT authentication
curl -H "Authorization: Bearer your_pat_token" \
"https://jira.your-company.com/rest/api/2/myself"
```
**Cause:** Your account doesn't have permission for the requested operation.
**Fix:**
* Verify your Jira/Confluence project permissions
* For write operations, ensure your account has edit permissions
* For admin-only fields, you may need project admin access
* Check if `READ_ONLY_MODE=true` is blocking write tools
**Cause:** OAuth access token has expired and refresh failed.
**Fix:**
1. Re-run the OAuth setup: `mcp-atlassian --oauth-setup`
2. Ensure your app has `offline_access` scope for refresh tokens
3. Check if the OAuth app is still active in your Atlassian developer console
## Field and Data Errors
**Cause:** Custom field ID doesn't exist or isn't available on the issue type.
**Fix:**
1. Use `jira_search_fields` to find the correct field ID
2. Check if the field is available on the target issue type's screen
3. Custom field IDs differ between Cloud and Server/DC instances
```json theme={null}
jira_search_fields: {"keyword": "story points"}
```
**Cause:** The specified issue type doesn't exist in the project.
**Fix:**
* Use `jira_get_all_projects` to see available issue types per project
* Issue type names are case-sensitive
* Some issue types (e.g., "Epic") may require specific project configurations
**Cause:** File exceeds the 50MB attachment limit.
**Fix:**
* MCP Atlassian limits inline attachment downloads to 50MB
* For larger files, access attachments directly via the Jira/Confluence web UI
* Consider compressing files before uploading
## Rate Limiting
**Cause:** You've exceeded the Atlassian API rate limit.
**Fix:**
* Atlassian Cloud: \~100 requests per minute per user (varies)
* Server/DC: depends on instance configuration
* Add delays between bulk operations
* Use batch tools (`jira_batch_create_issues`, `jira_batch_get_changelogs`) instead of individual calls
* Consider using `ENABLED_TOOLS` to limit which tools are available
## Connection Issues
**Cause:** Server/DC instance uses a self-signed or internal CA certificate.
**Fix:**
```bash theme={null}
# Disable SSL verification (not recommended for production)
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
```
For mTLS (mutual TLS) authentication:
```bash theme={null}
JIRA_CLIENT_CERT=/path/to/client-cert.pem
JIRA_CLIENT_KEY=/path/to/client-key.pem
```
**Cause:** Atlassian instance is unreachable or slow to respond.
**Fix:**
* Default timeout is 75 seconds
* Increase timeout for slow instances:
```bash theme={null}
JIRA_TIMEOUT=120
CONFLUENCE_TIMEOUT=120
```
* Check if a proxy is required:
```bash theme={null}
HTTPS_PROXY=https://proxy.example.com:8443
```
## Getting Help
* Check [GitHub Issues](https://github.com/sooperset/mcp-atlassian/issues) for known problems
* Review [SECURITY.md](https://github.com/sooperset/mcp-atlassian/blob/main/SECURITY.md) for security-related concerns
* Open a new issue with debug logs if the problem persists