atlassian-mcp

Read-only access to Jira Cloud and Confluence Cloud, served to Claude Code (or any MCP client) as a local stdio MCP server. No local index: both products are searched live.

Jira Cloud REST API v3        ──┐
(JQL search, issues+comments)   │  (same site, same email + API token)
                                 ├──► atlassian-mcp serve ──► Claude Code / agent-harness
Confluence Cloud REST API       │        (stdio / MCP)
(CQL search, pages)           ──┘

Everything runs on your machine; nothing is cached or stored outside Jira/Confluence themselves. Text the MCP tools return does go to the model provider as part of your conversation.

Requirements

Python packages (installed by pip below): mcp 2.x, requests, beautifulsoup4.

Related MCP server: Confluence MCP Server

Installation

git clone https://github.com/tealtadpole/local-atlassian-mcp.git
cd local-atlassian-mcp
python3 -m venv .venv
.venv/bin/pip install -e .              # add ".[dev]" to also install pytest

cp config.example.toml config.toml      # gitignored
chmod 600 config.toml
$EDITOR config.toml                     # at least base_url and email
export ATLASSIAN_API_TOKEN='...'        # or set token = "..." in config.toml

Then:

.venv/bin/atlassian-mcp check                        # tests credentials, lists projects + spaces
.venv/bin/atlassian-mcp jira-search 'project = ENG AND status = "In Progress"'
.venv/bin/atlassian-mcp jira-get ENG-123
.venv/bin/atlassian-mcp confluence-search "how do I request VPN access"
.venv/bin/atlassian-mcp confluence-get 12345

If you only use one of the two products, set enabled = false under [jira] or [confluence] in config.toml and that product's tools won't be registered at all.

Common problems

Use it from Claude Code

Run this from the repository folder ($PWD becomes the absolute path):

claude mcp add -s user atlassian \
  -e ATLASSIAN_API_TOKEN="$ATLASSIAN_API_TOKEN" \
  -- "$PWD/.venv/bin/atlassian-mcp" --config "$PWD/config.toml" serve

-e stores the token in Claude Code's MCP config (~/.claude.json). If you'd rather keep it only in config.toml, leave out -e. Restart Claude Code, then check /mcp. Tools:

To allow the read-only tools without permission prompts, add them to permissions.allow in ~/.claude/settings.json, e.g. "mcp__atlassian__search_jira".

Use it from agent-harness

Add it as another [mcp.servers.<name>] entry in agent-harness's config.toml:

[mcp.servers.atlassian]
command = "/abs/path/local-atlassian-mcp/.venv/bin/atlassian-mcp"
args = ["--config", "/abs/path/local-atlassian-mcp/config.toml", "serve"]
env = { ATLASSIAN_API_TOKEN = "${ATLASSIAN_API_TOKEN}" }
tools = ["search_jira", "get_jira_issue", "search_confluence", "get_confluence_page"]

Don't run this alongside local-confluence-RAG's Confluence tools at the same time. agent-harness doesn't namespace MCP tool names by server, and both expose tools named search_confluence / get_confluence_page. Use this one for Confluence Cloud, use local-confluence-RAG for Confluence Server/Data Center — not both.

Security notes

• Your token sees what you see. Searches run with your Atlassian permissions; don't share the server or expose it to other people.

• Keep the token out of files where you can (token_env). If it's in config.toml, the tool warns unless the file is chmod 600. It's never written to logs.

• Tool output is labelled as reference data, not instructions. Issues, comments and wiki pages are editable by many people and could contain prompt-injection text.

• The optional jira.projects / confluence.spaces allow-lists scope every search even if the token itself can see more — defense-in-depth, not a substitute for Atlassian's own permissions.

• Behind a corporate TLS proxy, set verify_ssl = "/path/to/corp-ca.pem".

Limitations

• Cloud only (email + API token, Basic Auth). Jira/Confluence Server or Data Center use a Bearer PAT and different REST versions; they'd need a different client in client.py. For Confluence Server/DC, see local-confluence-RAG.

• Read-only: search and read issues/pages/comments. No create, update, transition or delete tools.

• Jira search uses the newer /rest/api/3/search/jql endpoint (the deprecated /rest/api/3/search is not used). If Atlassian changes that endpoint's shape again, update client.py.

• Jira issue text is Atlassian Document Format (ADF); adf.py renders it to readable plain text, not a pixel-perfect reconstruction. Confluence page bodies are still storage-format XHTML on Cloud, rendered by textproc.py. Attachments and embedded media aren't fetched either way.

• Confluence search has no local index (live CQL search only); fine for interactive use, not a substitute for local-confluence-RAG's semantic search over a large wiki.

Layout

src/atlassian_mcp/
  config.py    load + validate config.toml, resolve the token
  client.py    read-only REST clients: shared auth/retries, JiraClient, ConfluenceClient
  adf.py       Atlassian Document Format (Jira) -> plain text
  textproc.py  Confluence storage-format XHTML -> plain text
  server.py    MCP tools (search_jira, get_jira_issue, search_confluence, get_confluence_page)
  cli.py       check / jira-search / jira-get / confluence-search / confluence-get / serve
tests/         runs against a fake Jira+Confluence Cloud HTTP server (`.venv/bin/pytest`)

License

MIT. Not affiliated with or endorsed by Atlassian. "Jira" and "Confluence" are trademarks of Atlassian.