custom-atlassian-mcp
Integrates with Atlassian Cloud, providing tools for managing Jira issues and Confluence pages.
Enables searching, creating, updating, and retrieving Confluence pages.
Allows searching, creating, updating, and transitioning Jira issues, as well as managing sprints.
Provides Agile-specific tools like listing sprints and adding issues to sprints for Jira Software boards.
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., "@custom-atlassian-mcp find all high priority bugs in project ABC"
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.
custom-atlassian-mcp
A small, self-hosted Model Context Protocol server that exposes Jira and Confluence Cloud to any MCP-compatible client (Claude Code, Claude Desktop, GitHub Copilot Agents, etc.) over stdio.
Built as a lightweight alternative to the (currently unavailable) public Confluence MCP — one Atlassian site, one API token, no frameworks.
What you get
Jira
jira_search— run a JQL query, get a compact issue listjira_get_issue— full issue with description and recent comments (ADF → text)jira_add_comment— append a plain-text commentjira_update_issue— edit summary, description, assignee, priority, labelsjira_create_issue— create issues, optionally linked to an epic or parentjira_transition_issue— list transitions or move an issue through workflowjira_list_sprints— list sprints for a Jira Software board (Agile API)jira_add_issues_to_sprint— move issues into a sprint
Confluence
confluence_search— CQL search across spaces and pagesconfluence_get_page— fetch a page as plain text or raw storage-format XHTMLconfluence_create_page— create a page under a space (optionally under a parent)confluence_update_page— update body/title; supports drafts and publishing
Related MCP server: Jira Cloud MCP Server
Requirements
Node.js 18+ (uses the built-in
fetch)An Atlassian Cloud site and an API token (create one at https://id.atlassian.com/manage-profile/security/api-tokens)
Install
git clone https://github.com/shamshodisaev/custom-atlassian-mcp.git
cd custom-atlassian-mcp
npm install
npm run buildnpm run build compiles TypeScript to dist/ and marks dist/index.js
executable.
Configure
The server reads three environment variables:
Variable | Example | Description |
|
| Your Atlassian Cloud host (no protocol, no trailing slash) |
|
| Email of the account that owns the API token |
|
| API token from the Atlassian profile page |
For local runs you can copy .env.example to .env and fill it in — but the
MCP server itself does not load .env automatically. Either export the
vars in your shell, launch the server via node --env-file=.env dist/index.js,
or pass them through your MCP client's config (see below).
Wire it into an MCP client
Claude Code
Add an entry to your Claude Code MCP config (typically ~/.claude.json under
mcpServers, or via claude mcp add):
{
"mcpServers": {
"atlassian": {
"command": "node",
"args": ["/absolute/path/to/custom-atlassian-mcp/dist/index.js"],
"env": {
"ATLASSIAN_SITE": "your-org.atlassian.net",
"ATLASSIAN_EMAIL": "you@example.com",
"ATLASSIAN_API_TOKEN": "ATATT3x..."
}
}
}
}Restart Claude Code — the atlassian server should appear in /mcp and its
tools will be available as mcp__atlassian__jira_search, etc.
Claude Desktop
Add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or the equivalent on Windows/Linux.
Any other MCP client
Any client that can launch an stdio MCP server can use it — point it at
node /absolute/path/to/dist/index.js with the three env vars set.
Run standalone (for smoke testing)
export ATLASSIAN_SITE=your-org.atlassian.net
export ATLASSIAN_EMAIL=you@example.com
export ATLASSIAN_API_TOKEN=ATATT3x...
npm startThe server communicates over stdio, so it will look idle — that's expected. It's meant to be spawned by an MCP client, not talked to by hand. To exercise it interactively use the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsTool details
Jira
Search issues via JQL. Returns a compact summary per issue plus paging info.
Args
jql(string, required) — JQL query, e.g.project = ABC AND status = "In Progress"maxResults(number, 1–100, default 25)fields(string[], optional) — extra field names beyond the default summary set
Fetch a single issue with description and recent comments (ADF converted to text).
Args
key(string, required) — e.g.ABC-123includeComments(boolean, default true)
Append a plain-text comment. The text is wrapped into a single ADF paragraph.
Args
key(string, required)body(string, required)
Update editable fields. Only provided fields are changed.
Args
key(string, required)summary,description,priority(strings, optional)assigneeAccountId(string, optional; use"unassigned"to clear)labels(string[], optional — replaces existing labels)
Create a new issue. Description text is converted to ADF.
Args
projectKey(string, required),summary(string, required)issueType(string, defaultTask)description,assigneeAccountId,priority(strings, optional)labels(string[], optional)epicKey(string, optional) — sets Epic Link viacustomfield_10014(company-managed projects)parentKey(string, optional) — setsparent(team-managed projects, sub-tasks)
Omit transition to list available transitions; supply it (by id or name) to apply one.
Args
key(string, required)transition(string, optional)
List sprints for a Jira Software board (Agile API).
Args
boardId(string or number, required)state(active|future|closed, optional)
Move issues into a sprint (Agile API).
Args
sprintId(string or number, required)issueKeys(string[], required, min 1)
Confluence
Search content with CQL, e.g. space = ENG AND title ~ "onboarding".
Args
cql(string, required)limit(number, 1–50, default 15)
Fetch a page by id.
Args
pageId(string, required)format(text(default) |storage) —textstrips HTML;storagereturns raw XHTML
Create a page under a space. The body is treated as Confluence storage-format
XHTML — pass HTML-like markup, not markdown. Plain text is accepted and wrapped
in <p>.
Args
spaceKey(string, required) — resolved to a spaceId internallytitle(string, required)body(string, required)parentId(string, optional)
Update a page's body (and optionally title/status). Drafts stay at version 1
per Confluence's rules; pass status: "current" to publish a draft.
Args
pageId(string, required)body(string, required)title(string, optional)status(draft|current, optional)
Project layout
src/
index.ts # stdio entrypoint, wires the server + tools
client.ts # thin fetch wrapper with Basic auth + typed errors
adf.ts # tiny ADF <-> plain-text converter
tools/
jira.ts # jira_* tool registrations
confluence.ts # confluence_* tool registrationsDevelopment
npm run dev # tsc --watch
npm run build # compile once, chmod +x dist/index.js
npm start # node dist/index.js (needs env vars set)The MCP server is written against the official
@modelcontextprotocol/sdk.
Every tool is registered with a Zod schema — argument validation and the tool
manifest come from the same source.
Security notes
API tokens are as powerful as your account — treat them like passwords.
The included
.gitignoreblocks.env; keep it that way.All requests go directly from the server process to your Atlassian site over HTTPS with HTTP Basic auth (
email:tokenbase64-encoded). Nothing is proxied or logged.
License
No license granted. This is a personal utility — fork it if you want to use or modify it.
Available Tools
12 toolsconfluence_create_pageA
Create a new Confluence page. Body is treated as Confluence storage-format XHTML — pass HTML-ish markup, not markdown.
Inputs: body (required), title (required), spaceKey (required), parentId.
confluence_get_pageA
Fetch a Confluence page by id, including body (storage format converted to plain text).
Inputs: pageId (required), format.
confluence_searchA
Search Confluence content with CQL (e.g. 'space = ENG AND title ~ "onboarding"'). Returns title, space, and URL.
Inputs: cql (required), limit.
confluence_update_pageA
Update a Confluence page. Preserves draft/current status by default; drafts stay at version 1 (Confluence constraint). Pass status='current' to publish a draft.
Inputs: body (required), pageId (required), title, status.
jira_add_commentB
Add a plain-text comment to a Jira issue.
Inputs: key (required), body (required).
jira_add_issues_to_sprintA
Move one or more issues into a sprint (Agile API).
Inputs: sprintId (required), issueKeys (required).
jira_create_issueA
Create a new Jira issue. Description is converted from plain text to ADF. Use epicKey to link the issue to an epic (company-managed projects) or parentKey to nest it under a parent issue (team-managed projects or defect grouping). Stories and defects go in the NUTLA project; CAKE issues are Feature-type epics only.
Inputs: summary (required), projectKey (required), labels, epicKey, +5 more.
jira_get_issueA
Fetch a single Jira issue by key, including description and recent comments.
Inputs: key (required), includeComments.
jira_list_sprintsA
List sprints for a Jira Software board (Agile API). Filter by state to find the active sprint.
Inputs: boardId (required), state.
jira_searchA
Search Jira issues with a JQL query. Returns a compact list (key, summary, status, assignee, priority, updated).
Inputs: jql (required), fields, maxResults.
jira_transition_issueA
List available transitions for an issue, or apply a transition by id or name.
Inputs: key (required), transition.
jira_update_issueA
Update editable fields on a Jira issue. Description is converted from plain text to ADF.
Inputs: key (required), labels, summary, priority, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: Jira issues vs sprints vs comments, Confluence pages vs search. No two tools have overlapping purposes, and descriptions clarify even similar verbs like update_issue vs transition_issue.
All tools follow a consistent snake_case pattern with a domain prefix (jira_/confluence_) and verb. Minor deviations: search omits an object (e.g., jira_search vs jira_get_issue) and add_issues uses plural, but the pattern is still predictable.
12 tools is well-scoped for an Atlassian server covering Jira and Confluence. Each tool earns its place, covering search, read, create, update, and specialized actions without bloat.
Core CRUD and lifecycle operations are covered for both Jira (search, get, create, update, transition, comment, sprint management) and Confluence (search, get, create, update). Missing delete operations and project/space listing are minor gaps that agents can work around.
Maintenance
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for integrating with Jira Server instances, enabling natural language interactions to create, update, search, and manage issues and comments.1MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for interacting with Jira Cloud instances. Enables issue management, JQL queries, project and sprint management, and batch operations via natural language interfaces.141 npm4MIT
- AlicenseAqualityBmaintenanceMCP server for Jira Cloud enabling issue tracking, comments, transitions, and attachments management through natural language.5MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Atlassian Confluence and Jira, enabling AI assistants to search, create, and update issues and pages via natural language.MIT