Atlassian Jira MCP Server

A Node.js/TypeScript Model Context Protocol (MCP) server for Atlassian Jira Cloud. Enables AI systems (e.g., LLMs like Claude or Cursor AI) to securely interact with your Jira projects, issues, comments, and related development information in real time.

Why Use This Server?

Minimal Input, Maximum Output: Simple identifiers provide comprehensive details without requiring extra flags.
Complete Jira Context: Access projects, issues, comments, and metadata to understand your work context.
Rich Development Information: Get insights into branches, commits, and pull requests linked to issues.
Secure Local Authentication: Run locally with your credentials, never storing tokens on remote servers.
Intuitive Markdown Responses: Well-structured, consistent Markdown formatting for all outputs.

What is MCP?

Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements MCP for Jira Cloud, enabling AI assistants to interact with your Jira instance programmatically.

Prerequisites

Node.js (>=18.x): Download
Atlassian Account with access to Jira Cloud

Setup

Step 1: Get Your Atlassian API Token

Go to your Atlassian API token management page: https://id.atlassian.com/manage-profile/security/api-tokens
Click Create API token.
Give it a descriptive Label (e.g., mcp-jira-access).
Click Create.
Copy the generated API token immediately. You won't be able to see it again.

Step 2: Configure Credentials

Option A: MCP Config File (Recommended)

Edit or create ~/.mcp/configs.json:

{
	"jira": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "<YOUR_SITE_NAME>",
			"ATLASSIAN_USER_EMAIL": "<YOUR_ATLASSIAN_EMAIL>",
			"ATLASSIAN_API_TOKEN": "<YOUR_COPIED_API_TOKEN>"
		}
	}
}

<YOUR_SITE_NAME>: Your Jira site name (e.g., mycompany for mycompany.atlassian.net).
<YOUR_ATLASSIAN_EMAIL>: Your Atlassian account email.
<YOUR_COPIED_API_TOKEN>: The API token from Step 1.

Option B: Environment Variables

export ATLASSIAN_SITE_NAME="<YOUR_SITE_NAME>"
export ATLASSIAN_USER_EMAIL="<YOUR_EMAIL>"
export ATLASSIAN_API_TOKEN="<YOUR_API_TOKEN>"

Step 3: Install and Run

Quick Start with `npx`

npx -y @aashari/mcp-server-atlassian-jira ls-projects

Global Installation

npm install -g @aashari/mcp-server-atlassian-jira
mcp-atlassian-jira ls-projects

Step 4: Connect to AI Assistant

Configure your MCP-compatible client (e.g., Claude, Cursor AI):

{
	"mcpServers": {
		"jira": {
			"command": "npx",
			"args": ["-y", "@aashari/mcp-server-atlassian-jira"]
		}
	}
}

MCP Tools

MCP tools use snake_case names, camelCase parameters, and return Markdown-formatted responses.

jira_ls_projects: Lists accessible Jira projects (name: str opt, limit: num opt, startAt: num opt, orderBy: str opt). Use: View available projects.
jira_get_project: Gets detailed project information (projectKeyOrId: str req). Use: Access project components and metadata.
jira_ls_issues: Searches for Jira issues (jql: str opt, projectKeyOrId: str opt, statuses: str[] opt, orderBy: str opt, limit: num opt, startAt: num opt). Use: Find issues matching criteria.
jira_get_issue: Gets comprehensive issue details (issueIdOrKey: str req). Use: View issue with comments and development info.
jira_ls_comments: Lists comments for an issue (issueIdOrKey: str req, limit: num opt, startAt: num opt, orderBy: str opt). Use: Read issue discussion.
jira_add_comment: Adds comment to an issue (issueIdOrKey: str req, commentBody: str req). Use: Add feedback to issues.
jira_ls_statuses: Lists available workflow statuses (projectKeyOrId: str opt). Use: Check valid status transitions.

MCP Tool Examples (Click to expand)

`jira_ls_projects`

Basic List Projects:

{}

Filtered Projects:

{
	"name": "Platform",
	"limit": 10,
	"orderBy": "name"
}

`jira_get_project`

Get Project by Key:

{ "projectKeyOrId": "DEV" }

Get Project by ID:

{ "projectKeyOrId": "10001" }

`jira_ls_issues`

Search with JQL:

{ "jql": "project = DEV AND status = 'In Progress'" }

Filter by Project and Status:

{
	"projectKeyOrId": "DEV",
	"statuses": ["In Progress", "To Do"],
	"limit": 15
}

`jira_get_issue`

Get Issue Details:

{ "issueIdOrKey": "PROJ-123" }

`jira_ls_comments`

List Comments:

{ "issueIdOrKey": "PROJ-123" }

Sorted Comments:

{
	"issueIdOrKey": "PROJ-123",
	"limit": 10,
	"orderBy": "created DESC"
}

`jira_add_comment`

Add Comment:

{
	"issueIdOrKey": "PROJ-123",
	"commentBody": "Thanks for the update. I'll review this by end of day."
}

`jira_ls_statuses`

List All Statuses:

{}

Project-Specific Statuses:

{ "projectKeyOrId": "DEV" }

CLI Commands

CLI commands use kebab-case. Run --help for details (e.g., mcp-atlassian-jira ls-projects --help).

ls-projects: Lists Jira projects (--name, --limit, --start-at, --order-by). Ex: mcp-atlassian-jira ls-projects.
get-project: Gets project details (--project-key-or-id). Ex: mcp-atlassian-jira get-project --project-key-or-id DEV.
ls-issues: Searches for issues (--jql, --project-key-or-id, --statuses, --order-by, --limit, --start-at). Ex: mcp-atlassian-jira ls-issues --project-key-or-id DEV.
get-issue: Gets issue details (--issue-id-or-key). Ex: mcp-atlassian-jira get-issue --issue-id-or-key PROJ-123.
ls-comments: Lists comments (--issue-id-or-key, --limit, --start-at, --order-by). Ex: mcp-atlassian-jira ls-comments --issue-id-or-key PROJ-123.
add-comment: Adds comment (--issue-id-or-key, --body). Ex: mcp-atlassian-jira add-comment --issue-id-or-key PROJ-123 --body "Comment text".
ls-statuses: Lists statuses (--project-key-or-id). Ex: mcp-atlassian-jira ls-statuses.

CLI Command Examples (Click to expand)

List Projects

Basic List:

mcp-atlassian-jira ls-projects

Filtered List:

mcp-atlassian-jira ls-projects --name "Platform" --limit 10 --order-by "name"

Get Project

mcp-atlassian-jira get-project --project-key-or-id DEV

List Issues

With JQL:

mcp-atlassian-jira ls-issues --jql "project = DEV AND status = 'In Progress'"

With Filters:

mcp-atlassian-jira ls-issues --project-key-or-id DEV --statuses "In Progress" "To Do" --limit 15

Get Issue

mcp-atlassian-jira get-issue --issue-id-or-key PROJ-123

List Comments

mcp-atlassian-jira ls-comments --issue-id-or-key PROJ-123 --order-by "created DESC"

Add Comment

mcp-atlassian-jira add-comment --issue-id-or-key PROJ-123 --body "This issue has been prioritized for the next sprint."

List Statuses

mcp-atlassian-jira ls-statuses --project-key-or-id DEV

Response Format

All responses are Markdown-formatted, including:

Title: Tool name and action performed.
Content: Structured data with headers, tables, and code blocks.
Pagination: Information about total results and navigation to additional pages.
Links: References to related resources when applicable.

Response Format Examples (Click to expand)

Project List Response

# Jira Projects

Showing **4** projects matching "Platform" out of 15 total projects.

| Key | Name | Lead | Issues |
|---|---|---|---|
| [PLAT](#) | Platform Services | Maria Johnson | 204 issues |
| [PLTX](#) | Platform Extensions | Chris Smith | 156 issues |
| [PAPI](#) | Platform API | Dev Team | 87 issues |
| [PINT](#) | Platform Integrations | Alex Wong | 42 issues |

*Retrieved from mycompany.atlassian.net on 2025-05-19 14:22 UTC*

Issue Details Response

# Issue: PROJ-123

**[PROJ-123](https://mycompany.atlassian.net/browse/PROJ-123): Implement OAuth2 authentication flow**

**Project:** [PROJ](#) (Project Name)
**Type:** 🛠️ Task
**Status:** 🟡 In Progress
**Priority:** 🔼 High
**Assignee:** Jane Doe
**Reporter:** John Smith
**Created:** 2025-05-01
**Updated:** 2025-05-18

## Description

We need to implement the OAuth2 authentication flow with the following requirements:

- Support authorization code flow
- Implement PKCE extension
- Store refresh tokens securely
- Add automatic token refresh

## Comments (3)

### John Smith - 2025-05-01
Initial requirements attached. See the authentication flow diagram.

### Jane Doe - 2025-05-15
I've started implementation. Questions about token expiration and storage.

### Project Lead - 2025-05-18
Looks good so far. Please add unit tests for token refresh logic.

## Development Information

**Branch:** feature/oauth2-auth
**Commits:** 7 commits by Jane Doe
**Pull Request:** [PR-45](https://github.com/mycompany/project/pull/45) (Open)

*Retrieved on 2025-05-19 14:25 UTC*

Development

# Clone repository
git clone https://github.com/aashari/mcp-server-atlassian-jira.git
cd mcp-server-atlassian-jira

# Install dependencies
npm install

# Run in development mode
npm run dev:server

# Run tests
npm test

Contributing

Contributions are welcome! Please:

Fork the repository.
Create a feature branch (git checkout -b feature/xyz).
Commit changes (git commit -m "Add xyz feature").
Push to the branch (git push origin feature/xyz).
Open a pull request.

See CONTRIBUTING.md for details.

License

ISC License

@aashari/mcp-server-atlassian-jira

Atlassian Jira MCP Server

Why Use This Server?

What is MCP?

Prerequisites

Setup

Step 1: Get Your Atlassian API Token

Step 2: Configure Credentials

Option A: MCP Config File (Recommended)

Option B: Environment Variables

Step 3: Install and Run

Quick Start with npx

Global Installation

Step 4: Connect to AI Assistant

MCP Tools

jira_ls_projects

jira_get_project

jira_ls_issues

jira_get_issue

jira_ls_comments

jira_add_comment

jira_ls_statuses

CLI Commands

List Projects

Get Project

List Issues

Get Issue

List Comments

Add Comment

List Statuses

Response Format

Project List Response

Issue Details Response

Development

Contributing

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Quick Start with `npx`

`jira_ls_projects`

`jira_get_project`

`jira_ls_issues`

`jira_get_issue`

`jira_ls_comments`

`jira_add_comment`

`jira_ls_statuses`

Weekly Downloads