@raviraj87/atlassian-mcp

v1.4.0

Published

2 months ago

Local MCP server for Jira, Bitbucket, and Confluence (Server/DC + Cloud)

0High
0Medium
0Low

raviraj87

mcp model-context-protocol jira bitbucket confluence atlassian cursor

Atlassian MCP

Local MCP server for Jira, Bitbucket, and Confluence. Gives Cursor (or any MCP client) tools to search issues, manage PRs, read wiki pages, and link Jira ↔ Bitbucket.

Runs on your machine (not cloud-hosted)
Uses REST API + personal tokens — no Atlassian Connect app
npm: @raviraj87/atlassian-mcp — https://www.npmjs.com/package/@raviraj87/atlassian-mcp
GitHub: https://github.com/raviraj-ntp/atlassian-mcp

Quick start (npm — recommended)

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@raviraj87/atlassian-mcp"],
      "env": {
        "JIRA_PAT": "your-jira-token",
        "BITBUCKET_USERNAME": "your-user",
        "BITBUCKET_TOKEN": "your-bitbucket-token"
      }
    }
  }
}

Add Jira/Bitbucket URLs via Setup B or ~/.atlassian-mcp.yaml (Setup A). Restart Cursor.

Install from source (optional)

git clone https://github.com/raviraj-ntp/atlassian-mcp.git
cd atlassian-mcp
npm install
npm run build

Then use "command": "node" and "args": ["<<YOUR_CLONE_PATH>>/atlassian-mcp/dist/index.js"] in mcp.json.

What you customize on each machine

Every user/machine needs their own values. Do not copy paths or tokens from someone else's config.

| What | Where | npm install | From source | |------|--------|-------------|-------------| | Server command | mcp.json | npx + @raviraj87/atlassian-mcp | node + path to dist/index.js | | API tokens | mcp.json → env | Your JIRA_PAT, BITBUCKET_TOKEN, etc. | Same | | Jira/Bitbucket URLs | YAML or env | Your company URLs | Same | | YAML config | Optional | Default ~/.atlassian-mcp.yaml | Same |

You do not need ATLASSIAN_MCP_CONFIG if your YAML file is at ~/.atlassian-mcp.yaml (the default).

Authentication (no Atlassian Connect)

| Product | Type | What you need | |---------|------|----------------| | Jira Server / DC | On-prem | JIRA_PAT | | Jira Cloud | Atlassian Cloud | ATLASSIAN_CLOUD_EMAIL + JIRA_CLOUD_PAT | | Bitbucket Server / DC | On-prem | BITBUCKET_USERNAME + BITBUCKET_TOKEN | | Bitbucket Cloud | Atlassian Cloud | BITBUCKET_WORKSPACE + username + app password | | Confluence Server / DC | On-prem | CONFLUENCE_PAT (or reuse JIRA_PAT if same PAT works) | | Confluence Cloud | Atlassian Cloud | ATLASSIAN_CLOUD_EMAIL + JIRA_CLOUD_PAT |

You can configure Jira only, Bitbucket only, Confluence only, or any combination.

Dual setup: on-prem + Cloud (recommended for enterprise)

Many users have both Jira Server and Confluence Cloud. Use YAML with two connections:

| Connection | Products | Env vars in mcp.json | Email? | |------------|----------|------------------------|--------| | corp | Jira Server, Bitbucket Server | JIRA_PAT, BITBUCKET_* | No — Server PAT only | | cloud | Confluence Cloud, Jira Cloud | ATLASSIAN_CLOUD_EMAIL, JIRA_CLOUD_PAT | Yes — Atlassian account email |

ATLASSIAN_CLOUD_EMAIL is from id.atlassian.com, not your corporate SSO username. On-prem Jira may show the same person as user key jdoe with email [email protected] — different auth mechanisms.

Scoped Cloud tokens (ATATT3x…) use the platform API URL; the server auto-fetches your site cloud_id from {site}/_edge/tenant_info — no manual ID needed.

How to get tokens

Jira Server/DC: Profile → Personal Access Tokens → create token → JIRA_PAT

Jira Cloud: Create API token → ATLASSIAN_CLOUD_EMAIL + JIRA_CLOUD_PAT

Bitbucket Server/DC: Personal settings → HTTP access tokens → BITBUCKET_USERNAME (account slug) + BITBUCKET_TOKEN

Bitbucket Cloud: Personal settings → App passwords → BITBUCKET_WORKSPACE + BITBUCKET_USERNAME + BITBUCKET_TOKEN

Confluence Server/DC: Personal access token → CONFLUENCE_PAT (often same as Jira Server PAT)

Confluence Cloud: Create API token with Confluence read + write scopes for full page control → ATLASSIAN_CLOUD_EMAIL + JIRA_CLOUD_PAT

Choose a setup style

| Style | When to use | Config file? | |-------|-------------|--------------| | A. YAML | Multiple environments (e.g. corp + cloud) | ~/.atlassian-mcp.yaml | | B. Env only | One Jira + one Bitbucket connection | None |

Setup A — YAML config

1. Create config (URLs only — no secrets in the file):

cp config.example.yaml ~/.atlassian-mcp.yaml
# Edit URLs in ~/.atlassian-mcp.yaml for your Jira/Bitbucket instances

2. Put secrets in Cursor (~/.cursor/mcp.json → env). Dual on-prem + Cloud example:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@raviraj87/atlassian-mcp"],
      "env": {
        "JIRA_PAT": "your-jira-server-pat",
        "JIRA_CLOUD_PAT": "your-atlassian-cloud-api-token",
        "ATLASSIAN_CLOUD_EMAIL": "[email protected]",
        "BITBUCKET_USERNAME": "your-bitbucket-user",
        "BITBUCKET_TOKEN": "your-bitbucket-token"
      }
    }
  }
}

Minimal (on-prem only):

"env": {
  "JIRA_PAT": "your-jira-token",
  "BITBUCKET_USERNAME": "your-user",
  "BITBUCKET_TOKEN": "your-bitbucket-token"
}

From source — replace command/args with:

"command": "node",
"args": ["<<YOUR_CLONE_PATH>>/atlassian-mcp/dist/index.js"]

Optional: use a different YAML file location:

"ATLASSIAN_MCP_CONFIG": "/path/on/your/machine/my-atlassian.yaml"

Optional: switch profiles per tool call: "connection": "cloud" (name from your YAML).

Setup B — Env only (no YAML)

Put everything in mcp.json env:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@raviraj87/atlassian-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_PAT": "your-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.example.com",
        "BITBUCKET_USERNAME": "your-user",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Jira Cloud — add "ATLASSIAN_CLOUD_EMAIL": "[email protected]" and "JIRA_CLOUD_PAT" (do not use Server JIRA_PAT for Cloud).

Bitbucket Cloud — use BITBUCKET_WORKSPACE instead of BITBUCKET_BASE_URL:

"BITBUCKET_WORKSPACE": "my-workspace",
"BITBUCKET_USERNAME": "my-user",
"BITBUCKET_TOKEN": "app-password"

Env variable reference

| Variable | Required when | Notes | |----------|---------------|-------| | JIRA_BASE_URL | Jira (env mode) | Server/DC or Cloud URL | | JIRA_PAT | Jira | API / personal access token | | JIRA_EMAIL | Jira/Confluence Cloud (legacy) | Alias for ATLASSIAN_CLOUD_EMAIL | | ATLASSIAN_CLOUD_EMAIL | Cloud Jira + Confluence | From id.atlassian.com account | | JIRA_CLOUD_PAT | Cloud Jira + Confluence | API token from id.atlassian.com (separate from Server JIRA_PAT) | | BITBUCKET_BASE_URL | BB Server/DC | Omit for Cloud | | BITBUCKET_WORKSPACE | BB Cloud | Workspace slug | | BITBUCKET_USERNAME | Bitbucket | Account slug or username | | BITBUCKET_TOKEN | Bitbucket | HTTP token or app password | | CONFLUENCE_BASE_URL | Confluence (env mode) | Server/DC or Cloud URL | | CONFLUENCE_PAT | Confluence | API / personal access token | | CONFLUENCE_EMAIL | Confluence Cloud only | Omit for Server/DC | | ATLASSIAN_MCP_CONFIG | Rarely | Only if YAML is not at ~/.atlassian-mcp.yaml | | ATLASSIAN_DEFAULT_CONNECTION | Optional | Default YAML profile name |

Cursor setup

Edit ~/.cursor/mcp.json.
Use npm (npx + @raviraj87/atlassian-mcp) or Setup A / B above.
Restart Cursor. Check Settings → MCP.

From source only: "command": "node", "args": ["<<YOUR_CLONE_PATH>>/atlassian-mcp/dist/index.js"]

Dev from source: "command": "npx", "args": ["tsx", "<<YOUR_CLONE_PATH>>/atlassian-mcp/src/index.ts"]

Verify

In Cursor: "Use confluence_who_am_i with connection cloud" or "Use jira_who_am_i with connection corp"

Use dryRun: true on write tools (confluence_create_page, etc.) to validate payloads without saving.

Using tools

| Parameter | Purpose | |-----------|---------| | connection | YAML profile name (corp, cloud, …). Omit = default. | | dryRun | On write tools: true = validate only, no save. |

| You ask | Tool | |---------|------| | What's in PROJ-123? | jira_get_issue, jira_triage_issue | | My open tickets | jira_whats_on_my_plate | | PRs for PROJ-123 | find_prs_for_jira_issue | | Release notes from JQL | release_notes | | Read a Confluence runbook | confluence_get_page, confluence_search |

Tool reference

Jira (~55)

Issues, comments, worklogs, attachments, links, workflow, agile/sprints, projects, versions, components — plus jira_who_am_i, jira_api.

Bitbucket (~50)

Repos, branches, commits, PRs, review, tasks, code search, build status, webhooks — plus bitbucket_api.

Confluence (23)

| Area | Tools | |------|-------| | Pages | confluence_get_page, confluence_get_page_by_title, confluence_create_page, confluence_update_page, confluence_delete_page, confluence_get_page_children, confluence_get_page_history, confluence_restore_page_version, confluence_move_page | | Spaces | confluence_list_spaces, confluence_get_space, confluence_search | | Labels | confluence_add_label, confluence_remove_label | | Comments | confluence_get_comments, confluence_add_comment, confluence_update_comment, confluence_delete_comment | | Attachments | confluence_get_attachments, confluence_add_attachment, confluence_delete_attachment | | Utility | confluence_list_connections, confluence_who_am_i, confluence_api |

Page bodies use storage XHTML (<p>…</p>) for create/update. confluence_get_page returns body.storage, body.view, and plain body.text. Write tools support dryRun: true. Cloud tokens need read + write scopes.

Cross-product (8)

find_prs_for_jira_issue, find_jira_issues_for_pr, find_commits_for_jira_issue, open_pr_for_jira_issue, transition_jira_on_pr_event, comment_jira_with_pr_link, comment_pr_with_jira_summary, release_notes

Composite (6)

jira_triage_issue, jira_whats_on_my_plate, bitbucket_triage_pr, bitbucket_review_pull_request, bitbucket_open_pr_from_changes, daily_standup

| Area | Tools | |------|-------| | Issues | jira_get_issue, jira_search, jira_create_issue, jira_update_issue, jira_delete_issue, jira_assign_issue, jira_clone_issue, jira_move_issue, jira_bulk_update | | Comments | jira_get_comments, jira_add_comment, jira_update_comment, jira_delete_comment | | Worklogs | jira_get_worklogs, jira_add_worklog, jira_update_worklog, jira_delete_worklog | | Attachments | jira_get_attachments, jira_add_attachment, jira_delete_attachment | | Links | jira_create_issue_link, jira_delete_issue_link, jira_get_issue_link_types, jira_get_remote_links, jira_create_remote_link, jira_delete_remote_link | | Workflow | jira_get_transitions, jira_transition_issue, jira_get_changelog | | Social | jira_watch_issue, jira_unwatch_issue, jira_get_watchers, jira_add_vote, jira_remove_vote, jira_get_votes | | Projects | jira_get_projects, jira_get_project, jira_get_issue_types, jira_get_create_meta, jira_lookup_user, jira_get_groups, jira_get_fields | | Versions | jira_get_versions, jira_create_version, jira_update_version, jira_delete_version, jira_get_components, jira_create_component, jira_update_component, jira_delete_component | | Agile | jira_get_boards, jira_get_sprints, jira_create_sprint, jira_update_sprint, jira_delete_sprint, jira_get_sprint_issues, jira_move_issues_to_sprint, jira_rank_issues, jira_get_epic_issues, jira_get_board_epics, jira_get_board_backlog | | Utility | jira_list_connections, jira_who_am_i, jira_api |

| Area | Tools | |------|-------| | Repos | bitbucket_list_projects, bitbucket_list_repositories, bitbucket_search_repositories, bitbucket_get_repository, bitbucket_create_repository | | Branches | bitbucket_list_branches, bitbucket_get_branch, bitbucket_create_branch, bitbucket_delete_branch, bitbucket_list_tags, bitbucket_create_tag | | Commits | bitbucket_get_commit, bitbucket_list_commits | | PRs | bitbucket_list_pull_requests, bitbucket_get_pull_request, bitbucket_create_pull_request, bitbucket_update_pull_request, bitbucket_merge_pull_request, bitbucket_decline_pull_request, bitbucket_get_pull_request_diff, bitbucket_list_pull_request_commits, bitbucket_get_pr_changes | | Review | bitbucket_add_comment, bitbucket_delete_comment, bitbucket_list_pr_comments, bitbucket_set_pr_approval, bitbucket_set_review_status, bitbucket_add_pr_reviewer | | Tasks | bitbucket_list_pr_tasks, bitbucket_create_pr_task, bitbucket_update_pr_task, bitbucket_delete_pr_task, bitbucket_set_pr_task_status, bitbucket_convert_pr_item | | Code | bitbucket_get_file_content, bitbucket_list_directory, bitbucket_get_file_blame, bitbucket_search_code, bitbucket_search_files, bitbucket_find_in_files | | CI | bitbucket_get_build_status, bitbucket_set_build_status, bitbucket_list_webhooks, bitbucket_create_webhook, bitbucket_delete_webhook | | Other | bitbucket_search_users, bitbucket_manage_attachment, bitbucket_api |

npm scripts

| Command | Purpose | |---------|---------| | npm install | Install dependencies | | npm run build | Build dist/ (required before production use) | | npm run dev | Run with tsx (no build) | | npm run typecheck | Typecheck without emit |

Security

Never commit tokens. YAML holds URLs only; secrets go in mcp.json env.
Admin-capable: can create/update/delete issues, PRs, branches. Use dryRun: true when testing.

Troubleshooting

| Problem | Fix | |---------|-----| | Config file not found | Use Setup B env vars, or create ~/.atlassian-mcp.yaml | | Missing env variable | Add token to mcp.json env | | 401 / 403 Jira Cloud | Use ATLASSIAN_CLOUD_EMAIL + JIRA_CLOUD_PAT (not Server JIRA_PAT) | | 401 / 403 Bitbucket | Use account slug, not display name | | Confluence 404 on API | Cloud uses /wiki/rest/api; Server uses /rest/api — use confluence_api paths relative to prefix | | Tools missing in Cursor | Fix args path; run npm run build; restart Cursor | | Wrong machine paths | Use your clone path — never copy /Users/someone/... |