atlassian-readonly
This MCP server provides read-only Jira and Confluence retrieval and search capabilities.
Read a single Jira issue by issue key, with optional JMESPath projection.
Search Jira using JQL (bounded results, limit 1–50) with optional projection.
Read a Confluence page by numeric page ID, converting storage HTML to Markdown, with optional projection.
Search Confluence using CQL (bounded results, limit 1–50) with optional projection.
It has no write operations.
Provides read-only access to Confluence Cloud, allowing users to read pages and search using CQL.
Provides read-only access to Jira Cloud, allowing users to retrieve issues and search using JQL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@atlassian-readonly Search Jira for open bugs assigned to me and summarize them."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Atlassian Read-only
Read-only Jira and Confluence toolkit for AI agents — no write operations are possible.
📋 Table of Contents
Related MCP server: MCP Atlassian Server
Features
Capability | Jira | Confluence |
Read a single issue/page | ✅ | ✅ |
Search with query language | ✅ JQL | ✅ CQL |
Projections (JMESPath subset) | ✅ | ✅ |
Any allowlisted read endpoint | ✅ | ✅ |
Response size limits | ✅ | ✅ |
Secret redaction | ✅ | ✅ |
HTML→Markdown conversion | — | ✅ optional dependency |
Read-only by construction — only GET, allowlisted paths, no POST/PUT/PATCH/DELETE.
Three Ways to Use
Method | Best for | Setup |
Agent Skill | Casual queries via Claude/Copilot |
|
MCP Server | Persistent tool integration in VS Code, CLI, Claude Code | Config file |
Direct Script | Scripts, CI, token-efficient calls |
|
Quick Start
1. Install the skill
npx skills add AlexSchaap-TMMC/atlassian-readonly --skill atlassian-readonlyThe --skill argument is required because the GitHub repository may contain multiple skills (multiple directories under skills/). This flag tells the installer which skill directory to install. Without it, the installer wouldn't know which of potentially many skills to use.
2. Run setup
cd ~/.agents/skills/atlassian-readonly
npm run setupThat single command stores your credentials in the OS credential store (Windows
Credential Manager, macOS Keychain, or Linux Secret Service; falling back to
~/.config token files where none exists), enables the corporate certificate store
if it detects TLS inspection, and verifies both tokens against the live API.
Nothing is installed first: the scripts use Node built-ins only, so the skill works
straight after step 1. Non-interactive:
npm run setup -- "you@example.com" "<jira-token>" "<confluence-token>"Token creation and scope requirements are in skills/references/setup.md; the same file covers rotation, headless/WSL setups, and troubleshooting.
3. Ask your agent
Read HEC-123 and summarize its acceptance criteria.
Search Jira for open bugs assigned to me.
Search Confluence for pages about Kafka retry handling.💡 Finding space keys: When searching Confluence, use the space key (not display name). Run
node ./skills/atlassian.mjs confluence search --cql 'title ~ "project-name"'first to discover the correct space key from results.
Direct Script Execution
For fast, token-efficient access, run the bundled script directly:
💡 Corporate networks: Prepend
NODE_OPTIONS="--use-system-ca"for Zscaler/corporate TLS.
# Read a Jira issue
node ./skills/atlassian.mjs jira get-issue --issue-key HEC-123
# Search Jira with JQL
node ./skills/atlassian.mjs jira search-issues --jql 'project=HEC AND status="To Do"' --limit 10
# Read a Confluence page
node ./skills/atlassian.mjs confluence get-page --page-id 123456789
# Search Confluence with CQL
node ./skills/atlassian.mjs confluence search --cql 'title ~ "Kafka"' --limit 10For an "open" filter use status, not statusCategory: statusCategory=Open returns 0
issues on this tenant. See
troubleshooting.
Projections
Reduce response size with --projection (a JMESPath subset, no dependency needed):
node ./skills/atlassian.mjs jira search-issues \
--jql 'project=HEC' \
--projection 'issues[*].{key: key, summary: fields.summary, status: fields.status.name}'
node ./skills/atlassian.mjs confluence get-page \
--page-id 123 \
--projection 'title,body[storage].value'JMESPath object shorthand {key, summary} is invalid — object entries need explicit
name: expression pairs, and nested fields must use their full path. Supported syntax is
a.b.c, [0], [-1], ["key"], [*], {k: expr}, |, @ and length(); filters,
slices and other functions are rejected with an explicit error.
Any Other Read Endpoint
Use get for allowlisted GET paths the named commands do not cover:
node ./skills/atlassian.mjs jira get \
--path '/rest/api/3/issue/HEC-123/changelog' --projection 'values[*].id'
node ./skills/atlassian.mjs confluence get \
--path '/wiki/api/v2/pages' --query 'limit=5&sort=-created-date' --projection 'results[*].{t: title}'Validate Tokens
Check tokens before API calls to avoid wasted requests:
node ./skills/atlassian.mjs test jira # exit 0 = valid, exit 1 = invalid
node ./skills/atlassian.mjs test confluenceMCP Server
The bundled server exposes four tools via stdio:
Tool ID | Description |
| Read a single Jira issue |
| Search Jira with JQL |
| Read a Confluence page |
| Search Confluence with CQL |
GitHub Copilot in VS Code
Run MCP: Open User Configuration from the Command Palette, then add:
{
"servers": {
"atlassian-readonly": {
"type": "stdio",
"command": "node",
"args": ["./skills/server.mjs"],
"env": {
"ATLASSIAN_USER_EMAIL": "your.email@example.com",
"NODE_OPTIONS": "--use-system-ca"
}
}
}
}Reload VS Code, open Copilot Chat, select Configure Tools, and enable the four Atlassian tools.
GitHub Copilot CLI
copilot mcp add atlassian-readonly \
--env ATLASSIAN_USER_EMAIL="your.atlassian.email@example.com" \
--env NODE_OPTIONS="--use-system-ca" \
-- node ./skills/server.mjsClaude Code
Edit ~/.claude/mcp.json:
{
"servers": {
"atlassian-readonly": {
"command": "node",
"args": ["./skills/server.mjs"],
"env": {
"ATLASSIAN_USER_EMAIL": "your.email@example.com",
"NODE_OPTIONS": "--use-system-ca"
}
}
}
}Manual mcp.json
cp ./skills/references/mcp.json atlassian-readonly-mcp.jsonThen update args to the absolute path of skills/server.mjs and set
ATLASSIAN_USER_EMAIL. Load it into your client as mcpServers — the file holds one
server object, not the whole mcpServers map.
Create API Tokens
Open Atlassian API tokens and create two separate tokens (Jira and Confluence cannot share one).
Jira token
read:jira-workThis classic scope alone is verified for issue retrieval and JQL search. Atlassian rejects granular Jira scopes with 401 Unauthorized; scope does not match.
Confluence token
read:page:confluence
read:content-details:confluence
search:confluenceThese granular scopes are verified for CQL search and full page retrieval.
⚠️ Scopes are fixed at creation time. Copy each token immediately — the dialog won't show it again. Never place tokens in source files, config, shell history, issues, or chat.
Store & Rotate Credentials
npm run setup stores credentials for you. To rotate or remove them afterwards:
npm run configure -- jira # replace
npm run configure -- confluence # replace
npm run configure -- jira delete # remove
npm run configure -- confluence deleteTokens are saved in your OS credential store (Windows Credential Manager, macOS Keychain,
or Linux Secret Service), falling back to ~/.config/atlassian-<product>-token with mode
0600 where no credential store is reachable.
⚠️ Local deletion does not revoke the token at Atlassian. Revoke it separately from Atlassian's token management page.
Troubleshooting
See skills/references/setup.md for the full list, including why a valid token can be reported as invalid and how to confirm which credential source each product resolves from.
Corporate certificates (Zscaler, etc.)
TLS inspection re-signs HTTPS traffic with a corporate CA. npm run setup detects this
and records it in the git-ignored config.json; force it with npm run setup -- --system-ca. Alternatively set NODE_OPTIONS=--use-system-ca (supported Node.js
versions).
Or export the non-expired corporate CA as Base-64 PEM and set NODE_EXTRA_CA_CERTS to its path. Never disable TLS verification.
WSL
WSL uses a separate Linux trust store. Export the corporate root and intermediate certificates from Windows, save as .crt, then:
sudo cp *.crt /usr/local/share/ca-certificates/
sudo update-ca-certificatesRestart WSL before retrying HTTPS clients.
WSL & Headless Systems
npm run setup writes ~/.config/atlassian-<product>-token files (mode 0600) when no
device credential store is reachable — no manual steps needed. To place them by hand:
mkdir -p ~/.config
install -m 600 /dev/null ~/.config/atlassian-user-email
install -m 600 /dev/null ~/.config/atlassian-jira-token
install -m 600 /dev/null ~/.config/atlassian-confluence-token
printf '%s' "your.email@example.com" > ~/.config/atlassian-user-email
read -rsp "Jira API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-jira-token
read -rsp "Confluence API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-confluence-token
unset tokenOr set environment variables:
export ATLASSIAN_USER_EMAIL_FILE=~/.config/atlassian-user-email
export ATLASSIAN_JIRA_TOKEN_FILE=~/.config/atlassian-jira-token
export ATLASSIAN_CONFLUENCE_TOKEN_FILE=~/.config/atlassian-confluence-tokenATLASSIAN_<PRODUCT>_API_TOKEN is read at a higher priority than the credential
store, which is what you want in CI. Keep it process-scoped and never persist it in
desktop configuration.
Repository Layout
skills/
SKILL.md agent-facing instructions (kept short)
references/setup.md detailed setup and troubleshooting
setup.mjs one-command setup + verification
atlassian.mjs CLI and the read-only operations
jmespath.mjs projection evaluator (no dependencies)
server.mjs MCP stdio server (needs npm install)
credentials.mjs credential resolution + config.json TLS
wincred.mjs Windows Credential Manager reads, no dependencies
configure.mjs interactive rotate/remove
save-keyring-tokens.mjs
scripts/check-tokens.sh credential-store-free validator (curl)
scripts/run.sh TLS wrapper for atlassian.mjs
scripts/unpin-tokens.sh drop token-file pins from config.json
test/ node:test suites
DEPENDENCIES.md why the core has zero dependencies, and how to keep it that waynpm run check syntax-checks every entry point; npm test runs the unit tests; npm run setup -- --check verifies live credentials without changing anything.
Security
Defense in depth
┌─────────────────────────────────────────────────────┐
│ YOUR REQUEST │
└──────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Layer 2: Implementation Enforcement │
│ • GET only, paths restricted to an allowlist │
│ • No custom host or method │
│ • Response size-limited, secrets redacted │
└──────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Layer 1: Token Scopes │
│ • Jira: read:jira-work │
│ • Confluence: read:page, read:content-details, │
│ search:confluence │
│ • Atlassian rejects any write attempt │
└─────────────────────────────────────────────────────┘Key guarantees:
No writes possible — neither Atlassian nor this code allows write operations.
Allowlisted paths —
--pathaccepts only/rest/api/3/...and/wiki/...GETs.Bounded responses — size limits prevent excessive data exfiltration.
Secret redaction — common credential patterns are masked in output.
Visibility inherited — the runtime can only read content the token account can already access.
⚠️ Supplying a broader token weakens the token layer but does not enable write operations in this code.
See SECURITY.md for vulnerability reporting guidelines.
License
⚠️ Internal Use Only — This software was developed on Toyota hardware during Toyota work hours. It is intended for use by Toyota employees only.
TODO: Confirm the correct license and copyright holder with Toyota's internal IP/Legal team. The current LICENSE file may need updating.
Available Tools
4 toolsconfluence_get_pageA
Read a Confluence page by ID and convert storage HTML to Markdown. This server has no write operations.
Inputs: page_id (required), projection.
confluence_searchA
Search Confluence with CQL. Results are bounded; this server has no write operations.
Inputs: cql (required), limit, projection.
jira_get_issueA
Read one Jira issue. This server has no write operations.
Inputs: issue_key (required), projection.
jira_search_issuesB
Search Jira with JQL. Results and fields are bounded; this server has no write operations.
Inputs: jql (required), limit, projection.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: get versus search for both Jira and Confluence. There is no overlap or ambiguity between any pair, enabling precise tool selection.
All tool names follow a consistent product_action pattern with snake_case (e.g., jira_get_issue, confluence_search). The naming is uniform and predictable.
With 4 tools covering two products (Jira and Confluence) each having a get and search operation, the count is well-scoped for a read-only server. No tool feels redundant or missing.
The read-only surface provides essential get and search for both products. Minor gaps exist such as bulk fetch or additional metadata endpoints, but core querying needs are well covered.
Maintenance
Related MCP Connectors
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Gives AI assistants read access to your Dedox help centre and knowledge base articles.
Secure AI access to OpenOak tasks, notes, and Kanban boards.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Atlassian products (Confluence and Jira) through natural language, supporting both Cloud and Server/Data Center deployments. Allows searching, creating, and managing content across Jira issues and Confluence pages with flexible authentication options.Apache 2.0
- AlicenseAqualityDmaintenanceIntegrates with Atlassian Cloud products (Confluence and Jira) to enable AI assistants to search, read, create, and manage pages, issues, comments, attachments, and export content through natural language interactions.404,948 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to search, retrieve, and manage Confluence pages, and generate weekly status drafts from Jira activity.1-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to create, search, update, and manage Jira issues and Confluence pages via natural language through the Atlassian Cloud REST APIs.MIT