# 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
- TOOLSETS=jira_issues,jira_fields,jira_transitions
confluence-mcp:
image: ghcr.io/sooperset/mcp-atlassian:latest
env_file: .env.confluence
ports:
- "8002:8000"
environment:
- TRANSPORT=sse
- PORT=8000
- TOOLSETS=confluence_pages,confluence_comments
```
## 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
- TOOLSETS=default # Optional: restrict to core toolsets only
```
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, mTLS, and OAuth 2.0
MCP Atlassian supports four 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 multi-user HTTP deployments where clients send their own PATs, follow the
[Server/DC per-request authentication setup](/docs/http-transport#authentication-methods).
That setup uses non-empty server-side PAT values only to initialize the service
configuration; each request's `Authorization: Token ...` value replaces them.
Enterprise CA certificates in the OS trust store (Windows Certificate Store, macOS Keychain, Linux system CAs) are trusted automatically.
For self-signed certificates not in the OS trust store, set `JIRA_SSL_VERIFY=false` and/or `CONFLUENCE_SSL_VERIFY=false`.
## Client Certificate (mTLS) (Server/Data Center)
Use mutual TLS when your Jira or Confluence Server/Data Center instance requires a client certificate. This authentication method does not require a username, API token, or personal access token.
Set `*_CLIENT_CERT` to either a combined certificate-and-private-key PEM, or set it with the matching `*_CLIENT_KEY` when the certificate and key are separate files:
```bash theme={null}
JIRA_URL=https://jira.your-company.com
JIRA_CLIENT_CERT=/etc/mcp-atlassian/jira-client-cert.pem
JIRA_CLIENT_KEY=/etc/mcp-atlassian/jira-client-key.pem
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_CLIENT_CERT=/etc/mcp-atlassian/confluence-client-combined.pem
```
In the example, Jira uses separate certificate and key files, while Confluence uses a combined PEM. For a combined PEM, omit `*_CLIENT_KEY`. The matching `JIRA_*` and `CONFLUENCE_*` variables configure each service independently.
**Encrypted private keys are not supported.** If your key is passphrase-protected, decrypt it first:
```bash theme={null}
openssl rsa -in encrypted.key -out decrypted.key
```
`JIRA_CLIENT_KEY_PASSWORD` and `CONFLUENCE_CLIENT_KEY_PASSWORD` are recognised environment variables but will raise a configuration error at startup if set to a non-empty value.
If your Server/DC instance uses a self-signed or internal CA certificate alongside mTLS, set `JIRA_SSL_VERIFY=false` and/or `CONFLUENCE_SSL_VERIFY=false` as well.
When using mTLS as the sole authentication method, MCP clients that connect without an `Authorization` header (such as a locally running OpenCode instance) will be rejected by default. Set `ALLOW_GLOBAL_CRED_FALLBACK=true` to allow the server to use the configured certificate credentials for requests that carry no per-request auth header:
```bash theme={null}
ALLOW_GLOBAL_CRED_FALLBACK=true
```
Only set this when the server is not exposed to untrusted callers, as it allows any unauthenticated client to transact under the operator's certificate identity.
## 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.
### MCP OAuth Proxy (DCR + Discovery)
Enable this when running a remote MCP endpoint that should onboard MCP clients
through the standard OAuth discovery/DCR flow (`401` challenge, `/.well-known/*`,
`/register`, `/authorize`, `/token`, callback).
```bash theme={null}
ATLASSIAN_OAUTH_PROXY_ENABLE=true
PUBLIC_BASE_URL=https://mcp.example.com/mcp-atlassian
ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,http://127.0.0.1:*,https://chatgpt.com/connector_platform_oauth_redirect
ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES=authorization_code,refresh_token
ATLASSIAN_OAUTH_REQUIRE_CONSENT=true
```
This mode is opt-in. Existing API token, PAT, and header-based OAuth flows continue
to work without enabling the proxy.
The callback configured in `ATLASSIAN_OAUTH_REDIRECT_URI` is for the upstream
Atlassian identity provider, not a dynamically registered MCP client. A DCR
client's `redirect_uri` must be different from this OAuth proxy IdP callback.
Registration is rejected with `invalid_redirect_uri` if the two callbacks collide,
preventing a callback loop.
### 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) |
## MCP stdio readiness probe
Maintainers can exercise the public MCP initialize and `tools/list` boundary
without depending on FastMCP internals:
```bash theme={null}
uv run python scripts/mcp_wire_probe.py \
--server-command uv \
--server-arg=run \
--server-arg=mcp-atlassian
```
The default probe does not invoke any Atlassian tool. It emits machine-readable
JSON with the negotiated protocol version, discovered tool names, and installed
versions of MCP, MCP types, FastMCP, FastMCP slim, and cryptography. Missing
distributions are reported as `null`, making the output useful for comparing
supported SDK and framework environments.
Version-specific test lanes can make protocol negotiation an explicit gate:
```bash theme={null}
uv run python scripts/mcp_wire_probe.py \
--server-command uv \
--server-arg=run \
--server-arg=mcp-atlassian \
--expect-protocol-version=2025-11-25 \
--expect-tool-absent=jira_create_issue
```
The expected revision is lane-specific. Do not infer it from the installed MCP
SDK major version: an SDK can retain an older protocol revision unless the
newer protocol era is explicitly selected. See the MCP 2 / FastMCP 4 findings
in [issue #1541](https://github.com/sooperset/mcp-atlassian/issues/1541).
Repeat `--expect-tool-present` or `--expect-tool-absent` to make public tool
discovery an explicit gate. These checks run immediately after `tools/list` and
before any optional staging reads, so they can diagnose policy visibility
without contacting Atlassian. Contradictory expectations fail as a probe
configuration error.
An explicit `--staging-dc-pat` profile can additionally call one fixed Jira DC
issue and one fixed Confluence DC page. Configure these variables securely
before running it:
| Variable | Purpose |
| ---------------------------------- | ----------------------------------------------- |
| `MCP_READINESS_JIRA_URL` | Jira DC staging URL |
| `MCP_READINESS_JIRA_PAT` | Jira DC staging personal access token |
| `MCP_READINESS_JIRA_ISSUE_KEY` | Fixed issue approved for a read probe |
| `MCP_READINESS_CONFLUENCE_URL` | Confluence DC staging URL |
| `MCP_READINESS_CONFLUENCE_PAT` | Confluence DC staging personal access token |
| `MCP_READINESS_CONFLUENCE_PAGE_ID` | Fixed page approved for a read probe |
| `MCP_READINESS_MAX_RPM` | Optional request rate from 1–30; defaults to 30 |
Then add the live-profile flag to the preceding command:
```bash theme={null}
uv run python scripts/mcp_wire_probe.py \
--server-command uv \
--server-arg=run \
--server-arg=mcp-atlassian \
--staging-dc-pat
```
The profile fails closed: it forces read-only mode, exposes only
`jira_get_issue` and `confluence_get_page`, disables retries, limits concurrency
to one, and caps traffic at 30 requests per minute. It stops before a live call
if any unexpected tool is exposed. Output records only protocol and result
shape—it excludes credentials, URLs, request identifiers, and response bodies.
Direct-call policy regressions, including GHSA-3r68, are tested hermetically
with a mocked backend. The live staging profile intentionally does not call a
hidden write tool: if policy had regressed, such a canary could perform the
write it was intended to detect.
Passing this probe verifies the public MCP behaviors it exercises; it does not
by itself establish compatibility with a future FastMCP major version.
## 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). Current releases run on FastMCP v3 (`>=3.2.4,<4.0.0`) while exposing the standard MCP protocol over stdio and HTTP, so MCP clients do not need FastMCP installed. If an older client still cannot discover tools, update the client to a current MCP-compatible release.
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 |
| `confluence_check_content_permissions` | Yes | No | Cloud-only content permissions API |
| `confluence_get_space_permissions` | Yes | No | Cloud-only space permissions API |
| `confluence_search_user` | Yes (CQL) | Yes (group member fallback) | Server/DC uses group member API; specify `group_name` |
### 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"
}
}
}
}
```
For mTLS, replace the personal token variables with client certificate variables. Use a combined certificate-and-private-key PEM in `*_CLIENT_CERT`, or use `*_CLIENT_CERT` and the matching `*_CLIENT_KEY` for separate files:
```json theme={null}
{
"mcpServers": {
"mcp-atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://jira.your-company.com",
"JIRA_CLIENT_CERT": "/etc/mcp-atlassian/jira-client-cert.pem",
"JIRA_CLIENT_KEY": "/etc/mcp-atlassian/jira-client-key.pem",
"CONFLUENCE_URL": "https://confluence.your-company.com/wiki",
"CONFLUENCE_CLIENT_CERT": "/etc/mcp-atlassian/confluence-client-combined.pem"
}
}
}
}
```
`JIRA_CLIENT_CERT` and `CONFLUENCE_CLIENT_CERT` can point to combined PEM files. If the private key is separate, set `JIRA_CLIENT_KEY` or `CONFLUENCE_CLIENT_KEY` as appropriate. Encrypted private keys aren't supported by the requests library, so decrypt them before starting MCP Atlassian instead of setting `JIRA_CLIENT_KEY_PASSWORD` or `CONFLUENCE_CLIENT_KEY_PASSWORD`.
### 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_CLIENT_CERT` | Jira mTLS client certificate PEM path (Server/DC), combined or certificate-only |
| `JIRA_CLIENT_KEY` | Jira mTLS private key PEM path when the certificate is separate (Server/DC) |
| `JIRA_CLIENT_KEY_PASSWORD` | Not supported for encrypted private keys; decrypt the key before use |
| `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_CLIENT_CERT` | Confluence mTLS client certificate PEM path (Server/DC), combined or certificate-only |
| `CONFLUENCE_CLIENT_KEY` | Confluence mTLS private key PEM path when the certificate is separate (Server/DC) |
| `CONFLUENCE_CLIENT_KEY_PASSWORD` | Not supported for encrypted private keys; decrypt the key before use |
| `CONFLUENCE_SSL_VERIFY` | SSL verification (`true`/`false`) |
| `MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE` | Use OS native trust store (`true`/`false`, default: `true`) |
| `MCP_ATLASSIAN_VALIDATION_CACHE_TTL` | Multi-user credential validation cache lifetime in seconds (`0` disables, default: `300`) |
| `MCP_ATLASSIAN_VALIDATION_CACHE_MAXSIZE` | Maximum cached multi-user credential validations (default: `100`) |
Encrypted private keys are not supported. Setting `JIRA_CLIENT_KEY_PASSWORD` or
`CONFLUENCE_CLIENT_KEY_PASSWORD` to a non-empty value will raise a configuration error
at startup. Decrypt the key first:
```bash theme={null}
openssl rsa -in encrypted.key -out decrypted.key
```
### 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` |
| `TOOLSETS` | Enable tool groups (see [Toolset Filtering](#toolset-filtering)) | `default`, `legacy`, `all`, `default,jira_agile` |
### Jira Key Validation
Jira tools validate their `issue_key` / `project_key` arguments before calling the
API. The defaults match the Cloud key format, which cannot be changed. On Server/Data
Center the format is an instance setting (`jira.projectkey.pattern`), so widen these
patterns if your instance allows keys the defaults reject — a leading digit, a single
character, or lowercase. An invalid regex is ignored (a warning is logged) and the
default is kept. Both are read once at startup.
| Variable | Description |
| -------------------------- | ------------------------------------------------------------------------------------ |
| `JIRA_ISSUE_KEY_PATTERN` | Regex accepted for `issue_key` arguments (default: `^[A-Z][A-Z0-9_]+-\d+(?:-\d+)*$`) |
| `JIRA_PROJECT_KEY_PATTERN` | Regex accepted for `project_key` arguments (default: `^[A-Z][A-Z0-9_]+$`) |
```bash theme={null}
# Data Center instance whose project keys may start with a digit (e.g. 4ME-123)
JIRA_ISSUE_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*-\d+(?:-\d+)*$
JIRA_PROJECT_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*$
```
### 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`) |
| `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1` | Download Confluence attachments via the v1 REST endpoint instead of the legacy `/download/` link (removed on Cloud). Unset = auto (v1 on Cloud, legacy on Server/DC); `true`/`false` to force. |
| `ATLASSIAN_OAUTH_PROXY_ENABLE` | Enable OAuth proxy + DCR + `/.well-known/*` routes (`true`/`false`) |
| `PUBLIC_BASE_URL` | Public base URL for OAuth discovery metadata |
| `ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS` | Comma-separated allowed redirect URI patterns for DCR clients |
| `ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES` | Comma-separated grant types allowed during DCR |
| `ATLASSIAN_OAUTH_REQUIRE_CONSENT` | Require local consent page before upstream redirect (`true`/`false`) |
| `IGNORE_HEADER_AUTH` | Bypass proxy-injected auth headers. For GCP Cloud Run, AWS ALB deployments where load balancers inject Authorization headers (`true`/`false`) |
See [.env.example](https://github.com/sooperset/mcp-atlassian/blob/main/.env.example) for all available options.
### HTTP Hardening
These optional safeguards are useful for protecting self-hosted Server/Data Center
instances from runaway request loops. They are disabled by default.
| Variable | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ATLASSIAN_RETRY_TOTAL` | Enable retries for transient `429/502/503/504` responses and connection errors. `0` or unset disables retries. |
| `ATLASSIAN_RETRY_BACKOFF` | Retry exponential backoff factor in seconds (default: `1.0` when retries are enabled). |
| `ATLASSIAN_RETRY_INCLUDE_WRITES` | Also retry write methods (`POST`/`PUT`/`PATCH`/`DELETE`). Use only when writes are known to be idempotent. |
| `ATLASSIAN_RETRY_IGNORE_RETRY_AFTER` | Ignore the server's `Retry-After` header and use exponential backoff instead. Enable this for gateways that emit bogus values such as `Retry-After: 0`. |
| `ATLASSIAN_MAX_CONCURRENT_REQUESTS` | Process-wide cap for concurrent Jira and Confluence requests. `0` or unset disables the cap. |
| `ATLASSIAN_REQUESTS_PER_SECOND` | Process-wide outbound request rate limit. `0` or unset disables the limit. |
| `ATLASSIAN_MAX_PAGINATION_LIMIT` | Clamp user-supplied page sizes for high-fanout list/search calls. `0` or unset disables clamping. |
| `ATLASSIAN_CIRCUIT_BREAKER_THRESHOLD` | Open a process-wide circuit breaker after this many consecutive `429/503` responses. `0` or unset disables it. |
| `ATLASSIAN_CIRCUIT_BREAKER_COOLDOWN` | Circuit breaker cooldown in seconds before allowing a probe request (default: `30.0`). |
## Proxy Configuration
MCP Atlassian supports routing API requests through HTTP/HTTPS/SOCKS proxies,
with optional PAC/WPAD auto-configuration.
| Variable | Description |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `HTTP_PROXY` | Global HTTP proxy URL |
| `HTTPS_PROXY` | Global HTTPS proxy URL |
| `SOCKS_PROXY` | Global SOCKS proxy URL |
| `NO_PROXY` | Global hosts to bypass proxy |
| `ATLASSIAN_PROXY_WPAD_ENABLE` | Enable global PAC/WPAD evaluation (`true`/`false`) |
| `ATLASSIAN_PROXY_WPAD_URL` | Global PAC URL (defaults to `http://wpad/wpad.dat` when enabled) |
| `JIRA_HTTP_PROXY`, `JIRA_HTTPS_PROXY`, `JIRA_SOCKS_PROXY`, `JIRA_NO_PROXY` | Jira-specific explicit proxy overrides |
| `JIRA_PROXY_WPAD_ENABLE`, `JIRA_PROXY_WPAD_URL` | Jira-specific PAC/WPAD overrides |
| `CONFLUENCE_HTTP_PROXY`, `CONFLUENCE_HTTPS_PROXY`, `CONFLUENCE_SOCKS_PROXY`, `CONFLUENCE_NO_PROXY` | Confluence-specific explicit proxy overrides |
| `CONFLUENCE_PROXY_WPAD_ENABLE`, `CONFLUENCE_PROXY_WPAD_URL` | Confluence-specific PAC/WPAD overrides |
Service-specific variables override global ones. PAC/WPAD is opt-in and is
only evaluated when no explicit proxy is configured for that service.
PAC/WPAD support is provided by the optional `wpad` extra. Install it with
`pip install "mcp-atlassian[wpad]"` or `uv add "mcp-atlassian[wpad]"` before
enabling the feature. The published Docker image includes this extra.
## 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 |
| `JIRA_PASSTHROUGH_HEADERS` | Incoming MCP request header names to pass through to Jira requests |
| `CONFLUENCE_PASSTHROUGH_HEADERS` | Incoming MCP request header names to pass through to Confluence requests |
**Format:** Static custom headers use comma-separated `key=value` pairs.
Passthrough headers use comma-separated header names.
```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 names only. Values are read from each incoming MCP HTTP request.
JIRA_PASSTHROUGH_HEADERS=X-SSO-User,X-Request-ID
CONFLUENCE_PASSTHROUGH_HEADERS=X-SSO-User,X-Request-ID
```
Passthrough headers are request-scoped and only apply to HTTP transports. If a
passthrough header name conflicts with a static custom header, the incoming
request header value is used for that request.
Only configure headers that are set by a trusted proxy or gateway. Clients can
control any passthrough header they are allowed to send to the MCP endpoint.
When external auth uses a client-supplied Jira or Confluence URL, configure
`MCP_ALLOWED_URL_DOMAINS`; dynamic URLs are rejected without this allowlist so
trusted session headers cannot be forwarded to an attacker-controlled host.
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"
```
### Toolset Filtering
Toolsets provide group-level tool control. Instead of listing individual tool names,
enable entire groups of related tools at once using the `TOOLSETS` environment variable.
```bash theme={null}
# Restrict to core tools only (~35 tools across 6 core toolsets)
TOOLSETS=default
# Core tools plus agile boards/sprints
TOOLSETS=default,jira_agile
# Deprecated tools only, for migration compatibility
TOOLSETS=legacy
# Core tools plus deprecated tools during migration
TOOLSETS=default,legacy
# All toolsets (same as current default when TOOLSETS is unset)
TOOLSETS=all
```
Command-line alternative:
```bash theme={null}
uvx mcp-atlassian --toolsets "default,jira_agile"
```
**Core toolsets** (included with `TOOLSETS=default`):
`jira_issues`, `jira_fields`, `jira_comments`, `jira_transitions`, `confluence_pages`, `confluence_comments`
The opt-in **`legacy` toolset** contains deprecated tools retained while users
migrate to their replacement tools. Use `TOOLSETS=legacy` to expose only those
tools, or combine it with another selection such as `TOOLSETS=default,legacy`.
It is not included in `TOOLSETS=default`.
When both `TOOLSETS` and `ENABLED_TOOLS` are set, they intersect — a tool must pass
both filters. If `TOOLSETS` is not set, all toolsets are currently enabled.
In v0.22.0, the default will change from all toolsets to 6 core toolsets only.
Set `TOOLSETS=all` explicitly to preserve current behavior.
Unknown toolset names are silently ignored. If **all** names are unknown, no tools are
enabled (fail-closed behavior to prevent accidental exposure).
See [Toolset Groups](/docs/tools-reference#toolset-groups) for the full list of available toolsets.
# 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", "body": "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 "
}
}
}
}
```
Set a URL and a non-empty server-side PAT value for each enabled service:
```bash theme={null}
JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=unused
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=unused
```
These values let the server build its URL, SSL, and proxy configuration at
startup. The PAT sent with each request replaces the corresponding
server-side value for that API call.
```json theme={null}
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Token "
}
}
}
}
```
Keep `ALLOW_GLOBAL_CRED_FALLBACK` disabled when using placeholder values.
Requests without a PAT are rejected by default; enabling fallback would
use the server-side value as a credential.
### 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
# Optional: enable MCP OAuth proxy + DCR/discovery endpoints
ATLASSIAN_OAUTH_PROXY_ENABLE=true
PUBLIC_BASE_URL=https://mcp.example.com/mcp-atlassian
```
### OAuth Discovery + DCR for MCP Clients
When `ATLASSIAN_OAUTH_PROXY_ENABLE=true`, the HTTP service exposes OAuth discovery
and DCR endpoints so MCP clients can onboard users through spec-aligned OAuth:
* `/.well-known/oauth-protected-resource`
* `/.well-known/oauth-authorization-server`
* `POST /register`
* `GET /authorize`
* `POST /token`
* callback route derived from `ATLASSIAN_OAUTH_REDIRECT_URI`
Use this for remote clients like ChatGPT/Codex that expect discovery + DCR.
The DCR client's `redirect_uri` must be different from the OAuth proxy's own IdP
callback. If a client tries to register the proxy callback as its redirect URI,
registration is rejected with `invalid_redirect_uri` to prevent a callback loop.
### 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())
```
* Requests without user-specific credentials are rejected unless `ALLOW_GLOBAL_CRED_FALLBACK=true`
* 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
# Include this extra when PAC/WPAD proxy routing is enabled
pip install "mcp-atlassian[wpad]"
# 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
# Include this extra when PAC/WPAD proxy routing is enabled
uv add "mcp-atlassian[wpad]"
# 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 98 MCP tools for Jira and Confluence — organized by category with quick links
MCP Atlassian provides **98 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
Customer requests, service desks, and queues
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
Inspect content and space permissions
List page templates and create pages from them
## Tool Access Control
### Toolset Groups
Toolsets group related tools for easier management via `TOOLSETS` env var or `--toolsets` flag.
**Jira Toolsets (16):**
| Toolset | Core | Tools |
| ----------------------- | :--: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_issues` | Yes | `jira_get_issue`, `jira_search`, `jira_get_project_issues`, `jira_create_issue`, `jira_batch_create_issues`, `jira_batch_get_changelogs`, `jira_update_issue`, `jira_assign_issue`, `jira_delete_issue`, `jira_move_issue` |
| `jira_fields` | Yes | `jira_search_fields`, `jira_get_field_options` |
| `jira_comments` | Yes | `jira_add_comment`, `jira_edit_comment` |
| `jira_transitions` | Yes | `jira_get_transitions`, `jira_transition_issue` |
| `jira_projects` | No | `jira_get_project_issue_types`, `jira_get_create_fields`, `jira_get_project_versions`, `jira_get_project_components`, `jira_get_all_projects`, `jira_search_projects`, `jira_get_project_fields`, `jira_create_version`, `jira_batch_create_versions`, `jira_update_version` |
| `jira_agile` | No | `jira_get_agile_boards`, `jira_get_board_issues`, `jira_get_sprints_from_board`, `jira_get_sprint_issues`, `jira_create_sprint`, `jira_update_sprint`, `jira_add_issues_to_sprint`, `jira_move_issues_to_backlog` |
| `jira_links` | No | `jira_get_link_types`, `jira_link_to_epic`, `jira_create_issue_link`, `jira_create_remote_issue_link`, `jira_remove_issue_link` |
| `jira_worklog` | No | `jira_get_worklog`, `jira_add_worklog` |
| `jira_attachments` | No | `jira_download_attachments`, `jira_get_issue_images` |
| `jira_users` | No | `jira_get_user_profile`, `jira_search_assignable_users` |
| `jira_watchers` | No | `jira_get_issue_watchers`, `jira_add_watcher`, `jira_remove_watcher` |
| `jira_service_desk` | No | `jira_get_service_desk_for_project`, `jira_get_service_desk_queues`, `jira_get_queue_issues`, `jira_get_request_types`, `jira_get_request_type_fields`, `jira_create_customer_request` |
| `jira_forms` | No | `jira_get_issue_proforma_forms`, `jira_get_proforma_form_details`, `jira_update_proforma_form_answers` |
| `jira_metrics` | No | `jira_get_issue_dates`, `jira_get_issue_sla` |
| `jira_development` | No | `jira_get_issue_development_info`, `jira_get_issues_development_info` |
| `jira_project_analysis` | No | `jira_get_project_epic_hierarchy`, `jira_get_cross_project_dependencies` |
**Confluence Toolsets (8):**
| Toolset | Core | Tools |
| ------------------------ | :--: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `confluence_pages` | Yes | `confluence_search`, `confluence_get_page`, `confluence_get_page_children`, `confluence_get_space_page_tree`, `confluence_create_page`, `confluence_update_page`, `confluence_update_page_section`, `confluence_delete_page`, `confluence_move_page`, `confluence_get_page_history`, `confluence_get_page_diff`, `confluence_get_page_restrictions`, `confluence_set_page_restrictions`, `confluence_copy_page` |
| `confluence_comments` | Yes | `confluence_get_comments`, `confluence_add_comment`, `confluence_reply_to_comment`, `confluence_get_inline_comments`, `confluence_add_inline_comment` |
| `confluence_labels` | No | `confluence_get_labels`, `confluence_add_label` |
| `confluence_users` | No | `confluence_search_user` |
| `confluence_analytics` | No | `confluence_get_page_views` |
| `confluence_attachments` | No | `confluence_upload_attachment`, `confluence_upload_attachments`, `confluence_get_attachments`, `confluence_download_attachment`, `confluence_download_content_attachments`, `confluence_delete_attachment`, `confluence_get_page_images` |
| `confluence_templates` | No | `confluence_list_page_templates`, `confluence_get_page_template`, `confluence_create_page_from_template` |
| `confluence_permissions` | No | `confluence_check_content_permissions`, `confluence_get_space_permissions` |
**Migration Toolsets (1):**
| Toolset | Core | Purpose | Tools |
| -------- | :--: | ----------------------------------------------------- | ------------------------------------- |
| `legacy` | No | Deprecated tools retained for migration compatibility | Deprecated tools as they are migrated |
```bash theme={null}
# All toolsets are enabled when TOOLSETS is not set.
# To restrict to core toolsets plus specific extras:
TOOLSETS=default,jira_agile,jira_attachments
# Enable deprecated tools only while migrating to their replacements:
TOOLSETS=legacy
# Enable all toolsets (98 tools)
TOOLSETS=all
# Command line
uvx mcp-atlassian --toolsets "default,jira_agile"
```
### 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` | No | 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. Requires the server to be able to read the path; for remote or containerized servers use 'content\_base64' instead. Provide either 'file\_path' or 'content\_base64', not both. |
| `content_base64` | `string` | No | (Optional) Base64-encoded file content to upload directly, without the server reading from disk. Use this when the server cannot access host file paths (e.g. a remote or containerized MCP server). Requires 'filename'. Provide either 'file\_path' or 'content\_base64', not both. |
| `filename` | `string` | No | (Optional) Attachment filename, including extension (e.g. 'report.pdf'). Required when using 'content\_base64'; it determines the attachment title and file type. Ignored when 'file\_path' is used. |
| `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. |
| **Examples:** | | | |
```json theme={null}
{"content_id": "12345678", "file_path": "/path/to/diagram.png", "comment": "Updated architecture diagram"}
```
```json theme={null}
{"content_id": "12345678", "content_base64": "SGVsbG8=", "filename": "hello.txt"}
```
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. |
On Confluence Cloud, attachment downloads automatically use the v1 REST endpoint (the legacy `/download/` link was removed and returns 401 for API/scoped tokens). Set `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1` explicitly only to override the automatic Cloud/Server/DC choice.
***
### 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' |
On Confluence Cloud, images are fetched via the v1 REST endpoint automatically (the legacy `/download/` link was removed and returns 401 for API/scoped tokens). Override with `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1`.
***
# 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 |
| `body` | `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') |
***
### Reply to Comment
Reply to an existing comment thread on a Confluence page.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | ---------------------------------------- |
| `comment_id` | `string` | Yes | The ID of the parent comment to reply to |
| `body` | `string` | Yes | The reply content in Markdown format |
| **Example:** | | | |
```json theme={null}
{"comment_id": "67890", "body": "Thanks for the feedback! I've updated the section."}
```
Get comment IDs from `confluence_get_comments`. Replies are threaded under the parent comment.
***
### Get Inline Comments
Get all inline comments for a Confluence page.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ---------------------------------------------- |
| `page_id` | `string` | Yes | The ID of the page to get inline comments from |
***
### Add Inline Comment
Add an inline comment anchored to a text selection on a 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 the inline comment to |
| `body` | `string` | Yes | The comment content in Markdown format |
| `text_selection` | `string` | Yes | The exact text on the page to anchor the inline comment to. Must match text that exists in the page content. |
| `text_selection_match_count` | `integer` | No | Total number of times the selected text appears on the page. Defaults to 1. |
| `text_selection_match_index` | `integer` | No | Zero-based index of which occurrence of the text to anchor to. Defaults to 0 (first occurrence). |
***
### 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, full page URL, or tiny link. For example: '123456789', '[https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title](https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title)', or '[https://example.atlassian.net/wiki/x/N4CIO](https://example.atlassian.net/wiki/x/N4CIO)'. 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. When Confluence supplies version details, the response metadata includes `version_author` (the author display name) and `version_date` (the raw ISO 8601 version timestamp).
***
### 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` | No | The content of the page. Format depends on content\_format parameter. Can be Markdown (default), wiki markup, storage format, or XHTML storage format. Either 'content' or 'content\_file' must be provided, but not both. |
| `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', 'storage', or 'xhtml'. Use 'xhtml' when providing Confluence XHTML storage format (same as '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' |
| `include_content` | `boolean` | No | (Optional) Whether to include page content in the response. Defaults to false since callers already have the content at create time |
| `emoji` | `string` | No | (Optional) Page title emoji (icon shown in navigation). Can be any emoji character like '📝', '🚀', '📚'. Set to null/None to remove. |
| `content_file` | `string` | No | (Optional) Absolute or relative filesystem path to read the page body from (UTF-8). Use this instead of 'content' when the body is too large to pass comfortably as a tool argument. Mutually exclusive with 'content'. |
| `page_width` | `string` | No | (Optional) Page layout width. Options: 'full-width', 'default'. Defaults to null (Confluence default). |
| `table_layout` | `string` | No | (Optional) Table width preset applied to all markdown tables. Options: 'full-width' (1800 px), 'wide' (960 px), 'default' (760 px). Only applies when content\_format is 'markdown'. |
| `subtype` | `string` | No | (Optional) Confluence page subtype. Use 'live' to create a Confluence Live Doc. Only supported for Confluence Cloud. |
| **Example:** | | | |
```json theme={null}
{"space_key": "DEV", "title": "Architecture Decision Record", "content": "## Context\n\nWe need to decide...", "parent_id": "98765432", "subtype": "live"}
```
Use Markdown for content — it's auto-converted to Confluence storage format. Specify `parent_id` to create as a child page. Set `subtype` to `live` on Confluence Cloud to create a Live Doc.
Exactly one of `content` or `content_file` must be provided.
***
### 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` | No | The new content of the page. Format depends on content\_format parameter and may be Markdown (default), wiki markup, storage format, or XHTML storage format. Either 'content' or 'content\_file' must be provided, but not both. |
| `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', 'storage', or 'xhtml'. Use 'xhtml' when providing Confluence XHTML storage format (same as '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' |
| `include_content` | `boolean` | No | (Optional) Whether to include page content in the response. Defaults to false since callers already have the content at update time |
| `emoji` | `string` | No | (Optional) Page title emoji (icon shown in navigation). Can be any emoji character like '📝', '🚀', '📚'. Set to null/None to remove. |
| `content_file` | `string` | No | (Optional) Absolute or relative filesystem path to read the new page body from (UTF-8). Use this instead of 'content' when the body is too large to pass comfortably as a tool argument. Mutually exclusive with 'content'. |
| `page_width` | `string` | No | (Optional) Page layout width. Options: 'full-width', 'default'. Defaults to null (preserve existing). |
| `table_layout` | `string` | No | (Optional) Table width preset applied to all markdown tables. Options: 'full-width' (1800 px), 'wide' (960 px), 'default' (760 px). Only applies when content\_format is 'markdown'. |
| **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.
Exactly one of `content` or `content_file` must be provided.
***
### 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 Space Page Tree
Get page hierarchy for a Confluence space as a flat list.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | --------- | -------- | ------------------ |
| `space_key` | `string` | Yes | Space key |
| `limit` | `integer` | No | Max pages to fetch |
***
### 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. |
***
### Update Page Section
Update a single section of a Confluence page without affecting the rest.
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 |
| `heading_text` | `string` | Yes | Exact text of the heading that starts the section to replace. Matching is case-sensitive. Use confluence\_get\_page with convert\_to\_markdown=false to inspect exact heading text when unsure. |
| `new_content` | `string` | Yes | Replacement content for the section body. Do NOT include the heading itself — only the body beneath it. Format is controlled by content\_format. |
| `content_format` | `string` | No | (Optional) Format of new\_content. Options: 'markdown' (default) or 'storage' (raw Confluence storage XML). Use 'storage' to insert macros or elements that markdown cannot express. |
| `is_minor_edit` | `boolean` | No | Whether this is a minor edit |
| `version_comment` | `string` | No | Optional comment for this version |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "heading_text": "Weekly Update", "new_content": "- Shipped v2.1\n- Started v2.2 planning", "version_comment": "Weekly sync"}
```
Use this instead of `confluence_update_page` when the page contains macros, layouts, task lists, or other Confluence-specific elements you don't want to lose. The tool fetches the page as raw storage XML, surgically replaces only the target section, and writes the full XML back — so everything outside the section is preserved exactly.
`heading_text` must match the heading exactly as it appears in Confluence (case-sensitive, no surrounding emoji — emoji in headings are stripped automatically). If the heading is not found, a `ValueError` is raised without updating the page.
***
### Move Page
Move a Confluence page to a new parent or space.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `page_id` | `string` | Yes | ID of the page to move |
| `target_parent_id` | `string` | No | Target parent page ID. If omitted with target\_space\_key, moves to space root. |
| `target_space_key` | `string` | No | Target space key for cross-space moves |
| `position` | `string` | No | Position: 'append' (default, move as child of target), 'above' (move before target as sibling), or 'below' (move after target as sibling) |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "target_parent_id": "98765432"}
```
Use `target_space_key` to move pages between spaces. Omit `target_parent_id` with a space key to move to the space root.
At least one of `target_parent_id` or `target_space_key` must be provided.
***
### Copy Page
Copy a Confluence page to a new location.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `source_page_id` | `string` | Yes | The ID of the page to copy |
| `destination_space_key` | `string` | Yes | Space key for the new page (e.g. 'DEV', 'TEAM') |
| `new_title` | `string` | Yes | Title for the new copied page |
| `destination_parent_id` | `string` | No | (Optional) Parent page ID in the destination space. When omitted the page is created at the space root. |
| `copy_attachments` | `boolean` | No | (Optional) Whether to copy attachments to the new page. Defaults to true. Only supported on Confluence Cloud. |
| **Example:** | | | |
```json theme={null}
{"source_page_id": "12345678", "destination_space_key": "DOCS", "new_title": "Copied Runbook", "destination_parent_id": "98765432"}
```
***
### Get Page Restrictions
Get view and edit restrictions for a Confluence page.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ------------------ |
| `page_id` | `string` | Yes | The ID of the page |
***
### Set Page Restrictions
Set view and edit restrictions on 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 restrict |
| `read_users` | `array` | No | (Optional) Account IDs (Cloud) or usernames (Server/DC) allowed to view the page. Empty list = unrestricted. |
| `read_groups` | `array` | No | (Optional) Group names allowed to view the page. |
| `edit_users` | `array` | No | (Optional) Account IDs (Cloud) or usernames (Server/DC) allowed to edit the page. |
| `edit_groups` | `array` | No | (Optional) Group names allowed to edit the page. |
Omitting all restriction lists or passing empty lists removes all page restrictions.
***
### Get Page Version Diff
Get a unified diff between two versions of 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'. |
| `from_version` | `integer` | Yes | Source version number |
| `to_version` | `integer` | Yes | Target version number |
| **Example:** | | | |
```json theme={null}
{"page_id": "12345678", "from_version": 1, "to_version": 3}
```
Use `confluence_get_page_history` to discover available version numbers. The diff is in unified format, showing additions and removals between versions.
***
# Confluence Permissions
Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-permissions
Inspect content and space permissions
### Check Content Permissions
Check whether a user or group can perform an operation on specific content.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `content_id` | `string` | Yes | Confluence content ID (page, blog post, comment, or attachment). Example: '123456789' |
| `user_identifier` | `string` | Yes | Account ID of the user (for subject\_type='user') or group ID (for subject\_type='group'). Example user account ID: '5b10a2844c20165700ede21g' |
| `operation` | `string` | Yes | The operation to check. Common values: 'read', 'update', 'delete', 'export', 'purge', 'administer', 'create\_or\_delete\_from\_view'. |
| `subject_type` | `string` | No | Whether the subject is a 'user' or a 'group'. Defaults to 'user'. |
| **Example:** | | | |
```json theme={null}
{"content_id": "12345678", "user_identifier": "5b10a2844c20165700ede21g", "operation": "read"}
```
This tool is only available for Confluence Cloud. Calling it on Server/Data Center raises `ValueError` because those deployments use different permission APIs.
***
### Get Space Permissions
List all permission assignments for a Confluence space.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `space_id` | `string` | Yes | Numeric ID of the Confluence space. This is the internal space ID, not the space key. Example: '98304'. You can find the space ID from the Confluence REST API (GET /wiki/api/v2/spaces) or from the space URL. |
| `limit` | `integer` | No | Maximum number of permission entries to return. Defaults to 25. |
| `cursor` | `string` | No | Optional pagination cursor from a previous response. |
| **Example:** | | | |
```json theme={null}
{"space_id": "98304", "limit": 50}
```
This tool is only available for Confluence Cloud. Calling it on Server/Data Center raises `ValueError` because those deployments use different permission APIs.
***
# 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 (Cloud) or group member API (Server/DC).
**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) |
| `group_name` | `string` | No | Group to search within on Server/DC instances (default: 'confluence-users'). Ignored on Cloud. |
On Server/DC, user search falls back to group member enumeration. Use `group_name` to search within a specific group if the default `confluence-users` doesn't include all users.
***
# Confluence Templates
Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-templates
List page templates and create pages from them
### List Page Templates
List Confluence page content templates.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `space_key` | `string` | No | Optional space key to list templates defined in that space. When omitted, global templates are returned. |
| `limit` | `integer` | No | Maximum number of templates to return. |
This tool is only available for Confluence Cloud. Calling it on Server/Data Center raises `ValueError` because those deployments do not expose the template REST API.
***
### Get Page Template
Get a Cloud page template by ID, including its storage-format body.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------------- |
| `template_id` | `string` | Yes | The ID of the template to retrieve. |
This tool is only available for Confluence Cloud. Calling it on Server/Data Center raises `ValueError` because those deployments do not expose the template REST API.
***
### Create Page from Template
Create a new Cloud page pre-populated with a template's body.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | --------------------------------------------- |
| `space_key` | `string` | Yes | Key of the space in which to create the page. |
| `title` | `string` | Yes | Title for the new page. |
| `template_id` | `string` | Yes | ID of the template to use as the page body. |
| `parent_id` | `string` | No | Optional ID of the parent page. |
This tool is only available for Confluence Cloud. Calling it on Server/Data Center raises `ValueError` because those deployments do not expose the template REST API.
***
# 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') |
| `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') |
| `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 |
***
### Add Issues to Sprint
Add issues to a Jira sprint.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | -------------------------------------------------- |
| `sprint_id` | `string` | Yes | Sprint ID to add issues to |
| `issue_keys` | `string` | Yes | Comma-separated issue keys (e.g., 'PROJ-1,PROJ-2') |
| **Example:** | | | |
```json theme={null}
{"sprint_id": "42", "issue_keys": "PROJ-1,PROJ-2,PROJ-3"}
```
Get sprint IDs from `jira_get_sprints_from_board`. Issue keys are validated server-side — invalid keys will cause an error.
***
### Move Issues to Backlog
Move issues to the backlog, removing them from any sprint.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | -------------------------------------------------- |
| `issue_keys` | `string` | Yes | Comma-separated issue keys (e.g., 'PROJ-1,PROJ-2') |
***
# 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') |
| `body` | `string` | Yes | Comment text in Markdown format |
| `visibility` | `string` | No | (Optional) Comment visibility as JSON string (e.g. '`{"type":"group","value":"jira-users"}`') |
| `public` | `boolean` | No | (Optional) For JSM/Service Desk issues only. Set to true for customer-visible comment, false for internal agent-only comment. Posted via the ServiceDesk API as a raw string; Jira Cloud renders it server-side and stores ADF (markdown observed to render on Cloud, without the client-side markdown-to-ADF guarantees of the regular comment path). Cannot be combined with visibility. If the issue's project is listed in JIRA\_INTERNAL\_ONLY\_PROJECTS, only public=false is accepted — public=true or omitting this field is rejected. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "body": "## Investigation\n\nFound the root cause in module X."}
```
Supports Markdown formatting. On Jira Cloud, mention users with `[~accountid:ACCOUNT_ID]` or `@[Display Name](accountid:ACCOUNT_ID)`. Use `visibility` parameter for restricted comments (e.g., service desk internal notes). The generated schema lists `body`, but callers may use `comment` as an equivalent input alias for the same comment text.
***
### 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 |
| `body` | `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). |
***
### Search Assignable Users
Search Jira users assignable in a given project or issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | `string` | Yes | Free-form text to search Jira users by: display name, username, or email substring (e.g. 'Smith', 'jane.doe', '[doe@example.com](mailto:doe@example.com)'). Server-side match is case-insensitive and partial. |
| `project_key` | `string` | No | Project key to scope the search to (e.g. 'DT'). Required if issue\_key is not given. |
| `issue_key` | `string` | No | Issue key to scope the search to (e.g. 'DT-779'). Required if project\_key is not given. |
| `limit` | `integer` | No | Maximum number of users to return (default 20). |
***
### Get Issue Watchers
Get the list of watchers for a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123') |
***
### Add Issue Watcher
Add a user as a watcher 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') |
| `user_identifier` | `string` | Yes | User to add as watcher. For Jira Cloud, use the account ID. For Jira Server/DC, use the username. |
***
### Remove Issue Watcher
Remove a user from watching 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') |
| `username` | `string` | No | Username to remove (for Jira Server/DC). |
| `account_id` | `string` | No | Account ID to remove (for Jira Cloud). |
***
# 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 (case-sensitive). Examples: 'stash' (Bitbucket Server), 'bitbucket', 'GitHub', 'githube' (GitHub Enterprise Server), 'GitLab'. If omitted, types are discovered automatically. |
| `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 (case-sensitive). Examples: 'stash' (Bitbucket Server), 'bitbucket', 'GitHub', 'githube' (GitHub Enterprise Server), 'GitLab'. If omitted, types are discovered automatically. |
| `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.
**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 |
| `include` | `string` | No | (Optional) Comma-separated sections to inline in the response, avoiding extra tool calls. Supported: all, remote\_links, transitions, watchers, changelog, comments, worklogs |
| `use_display_names` | `boolean` | No | When true, custom field keys in the output use human-readable display names (e.g. 'Story Points') instead of opaque IDs (e.g. 'customfield\_10243'). The 'names' expansion is added automatically. Standard fields are unaffected. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "fields": "summary,status,assignee", "comment_limit": 5, "include": "remote_links,transitions"}
```
Use `fields: "*all"` to get all fields including custom ones. Use `expand: "renderedFields"` for rendered HTML content. Use `include: "all"` to inline common enrichments that otherwise require separate tool calls. The response includes `browse_url`, a direct link to the issue in the Jira web UI.
Set `use_display_names: true` to get human-readable keys for custom fields instead of opaque IDs like `customfield_XXXXX`. If a display name conflicts with another output key, that custom field keeps its raw ID so no value is lost.
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. On Jira Cloud, use '`{expand:Title}`...`{expand}`' for a collapsible section. |
| `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). On Jira Cloud, mention users with `[~accountid:ACCOUNT_ID]` or `@[Display Name](accountid:ACCOUNT_ID)`. Use `{expand:Title}` and `{expand}` around content to create a collapsible section on Jira Cloud. For epics, provide `epic_name` parameter.
Cloud uses ADF format internally (auto-converted from Markdown). Server/DC uses wiki markup.
***
### Update Issue
Update an issue and optionally transition, comment, and log work.
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` | No | JSON string of fields to update. For 'assignee', provide a string identifier (email, name, or accountId). For 'description', provide text in Markdown format; on Jira Cloud, use '`{expand:Title}`...`{expand}`' for a collapsible section. 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'] |
| `transition` | `string` | No | (Optional) Transition name or ID. Transition names are resolved case-insensitively. |
| `comment` | `string` | No | (Optional) Comment text in Markdown format. |
| `comment_visibility` | `string` | No | (Optional) Comment visibility as a JSON string, for example '`{"type":"group","value":"jira-users"}`'. |
| `worklog` | `string` | No | (Optional) Time spent to log, such as '1h 30m'. |
| `worklog_started` | `string` | No | (Optional) ISO datetime when the worklog started. |
| `return_fields` | `string` | No | (Optional) Controls which fields of the updated issue are returned, to reduce response size and token usage. Defaults to '\*all' (the complete issue, which can be very large). TOKEN-SAVING TIP: after an update you usually do NOT need the whole issue back. Pass a comma-separated list of just the field(s) you care about (e.g., 'summary,duedate'), or a single light field such as 'status' for a minimal confirmation - this can cut the response by thousands of tokens. The issue 'key' is always returned regardless. If you later need other fields, fetch them on demand with jira\_get\_issue (which also supports field filtering). Use '\*all' only when you genuinely need the full updated issue. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "fields": "{\"summary\": \"Updated title\", \"description\": \"New description\"}", "transition": "Done", "comment": "Completed the work", "worklog": "1h"}
```
Save response tokens: after an update you rarely need the whole issue back. Set `return_fields` to only the field(s) you changed (e.g., `return_fields: "duedate"`) — this can cut thousands of tokens. Use `*all` only when you need the full updated issue.
`fields` is optional when you only need to transition, comment, or log work. If `transition` and `comment` are both provided, the issue is transitioned first and the comment is added separately afterward. Use `comment_visibility` to restrict the comment's visibility.
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') |
***
### Assign Issue
Assign a Jira issue to a user using the dedicated assignment endpoint.
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') |
| `assignee` | `string` | No | User identifier (email, display name, account ID, login name, or JIRAUSER key), or a JSON object string from jira\_search\_assignable\_users. Pass null or empty string to unassign. |
***
### Move Issue to Project
Move a Jira issue to a different project (Jira Cloud only).
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key to move (e.g., 'PROJ-123') |
| `target_project_key` | `string` | Yes | Key of the target project (e.g., 'OTHERPROJ'). The issue will keep its current issue type and may receive a new key in the target project. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "target_project_key": "OTHERPROJ"}
```
This tool is only available for Jira Cloud. The target project must support the issue's current type. Jira may assign a new issue key in the target project.
***
### 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. Rejected for projects listed in JIRA\_INTERNAL\_ONLY\_PROJECTS (a transition comment may be customer-visible on JSM and cannot be forced internal): transition without a comment, then post an internal note with jira\_add\_comment(public=false). |
| **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, versions, components, and cross-project and epic hierarchy analysis
### 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. Rejected when either linked issue belongs to a project listed in JIRA\_INTERNAL\_ONLY\_PROJECTS (a link comment may be customer-visible on JSM and cannot be forced internal): create the link without a comment, then post an internal note with jira\_add\_comment(public=false) on the relevant issue. |
| `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"}` ] |
***
### Update Version
Update an existing fix version in a Jira project.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | -------------------------------------------------- |
| `version_id` | `string` | Yes | Numeric ID of the version to update (e.g. '10001') |
| `name` | `string` | No | New name for the version |
| `description` | `string` | No | New description for the version |
| `start_date` | `string` | No | New start date (YYYY-MM-DD) |
| `release_date` | `string` | No | New release date (YYYY-MM-DD) |
| `archived` | `boolean` | No | Set archived flag (true to archive) |
| `released` | `boolean` | No | Set released flag (true to mark released) |
***
### Get Project Epic Hierarchy
Group a project's epics under their cross-project parent issues.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | ---------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ') |
| `max_epics` | `integer` | No | Maximum number of epics to fetch (1-500) |
***
### Get Cross-Project Dependencies
Find all cross-project issue links for a project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | ---------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ') |
| `max_issues` | `integer` | No | Maximum issues to scan for links (1-500) |
***
# 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' |
| `page_token` | `string` | No | (Optional) Pagination token from a previous search result. Cloud only — Server/DC uses start\_at for pagination. |
| `use_display_names` | `boolean` | No | When true, custom field keys in the output use human-readable display names (e.g. 'Story Points') instead of opaque IDs (e.g. 'customfield\_10243'). The 'names' expansion is added automatically. Standard fields are unaffected. |
| **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. Every issue in the response includes `browse_url`, a direct link to that issue in the Jira web UI.
Set `use_display_names: true` to get human-readable keys for custom fields instead of opaque IDs like `customfield_XXXXX`. If a display name conflicts with another output key, that custom field keeps its raw ID so no value is lost.
Cloud supports cursor-based pagination via `page_token` for deterministic results across large datasets. Continue by passing the response's `next_page_token` back as `page_token`; Server/DC uses `start_at` instead.
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' |
| `contains` | `string` | No | Case-insensitive substring filter on option values. Also matches child values in cascading selects. |
| `return_limit` | `integer` | No | Maximum number of results to return (applied after filtering). |
| `values_only` | `boolean` | No | If true, return only value strings in a compact JSON format instead of full option objects. |
| **Example:** | | | |
```json theme={null}
{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}
```
Use `contains` to filter large option lists (e.g., hundreds of values). Combine with `values_only: true` for a compact response.
***
### Get Project Issue Types
Get available issue types for a Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ---------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'JTEST') |
| **Example:** | | | |
```json theme={null}
{"project_key": "PROJ"}
```
The response includes each type's ID, name, description, subtask flag, and untranslated name when Jira provides one.
***
### Get Create Fields
Get fields available for creating an issue of a specific type.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'JTEST') |
| `issue_type_id` | `string` | Yes | The issue type ID (from get\_project\_issue\_types). Example: '10002' for Task. |
| **Example:** | | | |
```json theme={null}
{"project_key": "PROJ", "issue_type_id": "10002"}
```
Use `jira_get_field_options` to retrieve allowed values for a custom field.
Each field includes its field ID, name, required flag, and schema.
***
### Get Project Fields
Get the fields available on issues of a project (the create schema),
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------- |
| `project_key` | `string` | Yes | The project key, e.g. 'PROJ'. |
***
### Search Projects
Search for Jira projects by name or key prefix.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------------- | --------- | -------- | ----------------------------------------------------------- |
| `query` | `string` | Yes | Name or key prefix to search for |
| `max_results` | `integer` | No | Maximum number of results to return |
| `current_project_ids` | `string` | No | Comma-separated list of project IDs to exclude from results |
***
# Jira Service Desk
Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-service-desk
Customer requests, service desks, and queues
### 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) |
***
### Get Request Types
Get request types for a Jira Service Management 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 Request Type Fields
Get field definitions for a Jira Service Management request type.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | -------- | -------- | ---------------------------- |
| `service_desk_id` | `string` | Yes | Service desk ID (e.g., '4') |
| `request_type_id` | `string` | Yes | Request type ID (e.g., '23') |
***
### Create Customer Request
Create a Jira Service Management customer request.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `service_desk_id` | `string` | Yes | Service desk ID (e.g., '4') |
| `request_type_id` | `string` | Yes | Request type ID (e.g., '23') |
| `request_field_values` | `string` | Yes | JSON string of request field values keyed by field ID. Examples: - Summary and description: `{"summary": "Access issue", "description": "Cannot log in"}` - Multi-value field: `{"customfield_10001": ["alice", "bob"]}` |
| `raise_on_behalf_of` | `string` | No | (Optional) Jira user identifier for raiseOnBehalfOf. For Server/DC this is typically username or key; for Cloud use the identifier expected by your JSM instance. |
| `request_participants` | `string` | No | (Optional) JSON array string or comma-separated list of request participants. Examples: \["user1","user2"] or "user1,user2" |
| `attachments` | `string` | No | (Optional) JSON array string of files to attach to the created request. Each object must contain 'filename', 'mime\_type', and base64-encoded 'base64' content. Example: \[`{"filename": "log.txt", "mime_type": "text/plain", "base64": "aGVsbG8="}`] |
| `strict_on_behalf` | `boolean` | No | If true, fail immediately when raiseOnBehalfOf cannot be applied. If false, retry without raiseOnBehalfOf and return a fallback warning. |
***
# 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)
mcp-atlassian uses the OS native trust store by default (via
[truststore](https://truststore.readthedocs.io/)), so certificates
signed by enterprise CAs installed in Windows Certificate Store,
macOS Keychain, or the Linux system CA bundle are trusted
automatically.
If you still see SSL errors with **self-signed** certificates that
are **not** in the OS trust store, disable verification:
```bash theme={null}
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
```
To disable the OS trust store integration (fall back to the bundled
certifi CA bundle):
```bash theme={null}
MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE=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"
```
**Symptom:** Reading pages works, but `confluence_get_page_images` returns
`downloaded: 0` (every image `"Fetch failed"`) and `confluence_download_attachment` /
`confluence_download_content_attachments` fail. Logs show
`401 ... /wiki/download/attachments/...`.
**Cause:** Confluence Cloud removed the legacy `/download/attachments/...` endpoint
(changelog [CHANGE-2735](https://developer.atlassian.com/cloud/confluence/changelog/) /
["Deprecation of /download/attachments/ APIs"](https://community.developer.atlassian.com/t/deprecation-of-download-attachments-apis/94448)).
It now returns 401 for API-token / scoped-token auth, while metadata endpoints keep working.
**Fix:** On Cloud this is handled automatically — downloads use the v1 REST endpoint
`/rest/api/content/{id}/child/attachment/{aid}/download`. To force the behaviour, set
`CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1=true` (or `false` to keep the legacy link).
**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"}
```
**Symptom:** A tool call fails before reaching Jira with a validation error such as
`project_key: String should match pattern '^[A-Z][A-Z0-9_]+$'`, even though the
project exists and the key is correct.
**Cause:** `issue_key` and `project_key` arguments are validated against a regex
first. The defaults require an uppercase letter followed by at least one more
character, which is the fixed Cloud format. Server/Data Center instances configure
their own `jira.projectkey.pattern` and may allow keys the defaults reject — a
leading digit (`4ME`), a single character, or lowercase.
**Fix:** Widen the patterns to match your instance, then restart the server (they
are read once at startup):
```bash theme={null}
JIRA_ISSUE_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*-\d+(?:-\d+)*$
JIRA_PROJECT_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*$
```
See [Jira Key Validation](/docs/configuration#jira-key-validation).
**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, set either a combined cert/key PEM:
```bash theme={null}
JIRA_CLIENT_CERT=/path/to/client-combined.pem
```
Or set separate certificate and key files:
```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
```
* If your network uses PAC/WPAD, enable it explicitly:
```bash theme={null}
ATLASSIAN_PROXY_WPAD_ENABLE=true
ATLASSIAN_PROXY_WPAD_URL=http://wpad/wpad.dat
```
## 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