Jira Mcp

Jira MCP Server

[](https://badge.fury.io/js/raalarcon-jira-mcp-server) [](https://opensource.org/licenses/MIT) [](http://www.typescriptlang.org/) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) [](https://github.com/raalarcon9705/jira-mcp/actions/workflows/ci.yml)

The most complete open source Model Context Protocol (MCP) server for Jira & Atlassian. Connect any MCP-compatible AI client to your Jira instance in seconds — manage issues, sprints, comments, transitions, users, and Confluence pages without leaving your AI assistant.

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "raalarcon-jira-mcp-server"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Compatible AI Clients

| Client | Supported | |--------|-----------| | Claude Desktop | ✅ | | Claude Code | ✅ | | Cursor | ✅ | | Windsurf | ✅ | | Cline | ✅ | | Continue | ✅ | | Any MCP-compatible client | ✅ |

[](https://github.com/ellerbrock/open-source-badges/) [](http://makeapullrequest.com) [](https://github.com/raalarcon9705/jira-mcp/graphs/contributors) [](https://github.com/raalarcon9705/jira-mcp/stargazers)

Find This Server On

• MCP Market — MCP server marketplace
• MCP Servers — Awesome MCP Servers directory
• Claude Marketplaces — Claude plugins & MCP directory
• npm — npx raalarcon-jira-mcp-server

Features

• ✅ Project Management: List projects and issue types
• ✅ Issue CRUD: Create, read, update and delete issues
• ✅ Comments: Create, read, update and delete comments with enhanced pagination
• ✅ Transitions: Move issues between states
• ✅ Assignments: Assign issues to users
• ✅ User Management: Search and manage users
• ✅ Sprint Management: Complete agile sprint lifecycle management
• ✅ Wiki Integration: Access Confluence pages by URL identifier with HTML to text conversion
• ✅ Rich Text Support: Markdown to ADF conversion for formatted descriptions and comments
• ✅ Validation: Yup schema validation
• ✅ Authentication: Full Jira Cloud support
• ✅ Optimized Responses: Token-efficient field filtering
• ✅ Type Safety: Full TypeScript support

Installation

Option 1: Using npx (Recommended)

The easiest way to use this MCP server is with npx:

1. Configure your MCP client (e.g., Claude Desktop) with this configuration:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "raalarcon-jira-mcp-server"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

1. Get your Jira API token (see instructions below)

That's it! The server will be automatically downloaded and run when needed.

Option 2: Local Development

1. Clone the repository:

git clone https://github.com/raalarcon9705/jira-mcp.git
cd jira-mcp

1. Install dependencies:

npm install

1. Build the project:

npm run build

1. Configure your MCP client with the full path to the built server:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/full/path/to/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Note: Replace /full/path/to/jira-mcp/ with the actual absolute path to your project directory.

Getting API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a descriptive name
4. Copy the generated token

Usage

Using with npx (Recommended)

Once configured in your MCP client, the server will automatically start when needed. No additional setup required!

Rich Text Support with Markdown

The server now supports automatic Markdown to ADF conversion for issue descriptions and comments. Simply use Markdown syntax and it will be automatically converted to Atlassian Document Format (ADF).

Supported Markdown Elements

• Headers: # H1, ## H2, ### H3
• Text formatting: **bold**, *italic*
• Code: ` inline code and code blocks`
• Lists: - bullet lists and 1. numbered lists
• Links: [text](url)
• Blockquotes: > quoted text
• Checkboxes: - [x] completed task

Example Usage

// Create issue with Markdown description
create_issue({
  projectKey: 'PROJ',
  summary: 'Bug Report',
  description: `# Bug Report

## Description
This is a **critical** bug affecting the login system.

## Steps to Reproduce
1. Go to login page
2. Enter invalid credentials
3. Click login button

## Code Example
\`\`\`javascript
function login(username, password) {
  return authenticate(username, password);
}
\`\`\`

> **Note**: This bug was reported by multiple users.`,
});

// Create comment with Markdown
create_comment({
  issueKey: 'PROJ-123',
  body: `## Update

**Status**: Fixed ✅

- [x] Identified root cause
- [x] Implemented fix
- [x] Tested solution

The issue has been resolved.`,
});

Development

npm run dev

Production

npm run build
npm start

Testing with npx

You can also test the server directly with npx:

# Test the server
npx raalarcon-jira-mcp-server

# Or use with MCP Inspector
npx @modelcontextprotocol/inspector
# Then configure: command: "npx", args: ["-y", "raalarcon-jira-mcp-server"]

Available Tools

Projects

get_projects

Retrieves all projects accessible to the authenticated user.

Parameters:

• expand (optional): Additional data to include
• recent (optional): Number of recent projects (0-20)

Response: Array of projects with essential fields:

[
  {
    "key": "PROJ",
    "name": "Project Name",
    "id": "10001",
    "projectTypeKey": "software"
  }
]

get_issue_types

Gets all available issue types for a specific project.

Parameters:

• projectKey (required): Project key

Response: Array of issue types with essential fields:

[
  {
    "id": "10002",
    "name": "Task",
    "desc": "A small, independent piece of work",
    "subtask": false,
    "level": 0
  }
]

Issues

create_issue

Creates a new issue in Jira.

Parameters:

• projectKey (required): Project key
• summary (required): Issue summary
• issueType (required): Issue type (Bug, Story, Task, etc.)
• description (optional): Issue description
• priority (optional): Priority (Highest, High, Medium, Low, Lowest)
• assignee (optional): Assignee account ID
• labels (optional): Array of labels
• components (optional): Array of components
• fixVersions (optional): Array of fix versions
• customFields (optional): Custom field values

Response: Issue PROJ-123 created successfully

get_issue

Gets details of a specific issue (custom fields removed for token efficiency).

Parameters:

• issueKey (required): Issue key (e.g., PROJ-123)
• expand (optional): Additional information
• fields (optional): Specific fields to return

Response: Complete issue object with custom fields filtered out

update_issue

Updates an existing issue.

Parameters:

• issueKey (required): Issue key to update
• summary (optional): New summary
• description (optional): New description
• priority (optional): New priority
• assignee (optional): New assignee
• labels (optional): New labels
• components (optional): New components
• fixVersions (optional): New fix versions
• customFields (optional): Custom fields

Response: Issue PROJ-123 updated successfully

delete_issue

Deletes an issue.

Parameters:

• issueKey (required): Issue key to delete
• deleteSubtasks (optional): Delete subtasks too (default: false)

Response: Issue PROJ-123 deleted successfully

Comments

create_comment

Adds a comment to an issue.

Parameters:

• issueKey (required): Issue key
• body (required): Comment text (supports ADF format)
• visibility (optional): Visibility settings

Response: Comment 12345 created successfully

get_comments

Gets all comments for an issue.

Parameters:

• issueKey (required): Issue key
• startAt (optional): Start index (default: 0)
• maxResults (optional): Max comments (1-100, default: 50)

Response: Optimized comment structure:

{
  "total": 5,
  "start": 0,
  "max": 50,
  "items": [
    {
      "id": "12345",
      "author": "John Doe",
      "authorId": "account-id",
      "created": "2025-01-01T10:00:00.000Z",
      "text": "Comment text content"
    }
  ]
}

update_comment

Updates an existing comment.

Parameters:

• issueKey (required): Issue key
• commentId (required): Comment ID
• body (required): New comment text
• visibility (optional): New visibility settings

Response: Comment 12345 updated successfully

delete_comment

Deletes a comment.

Parameters:

• issueKey (required): Issue key
• commentId (required): Comment ID

Response: Comment 12345 deleted successfully

Transitions

get_transitions

Gets available transitions for an issue.

Parameters:

• issueKey (required): Issue key

Response: Array of transitions with essential fields:

[
  {
    "id": "21",
    "name": "In Progress",
    "desc": "The assignee is currently working on this activity",
    "toName": "In Progress",
    "toId": "3",
    "available": true,
    "category": "In Progress"
  }
]

transition_issue

Moves an issue to a different state.

Parameters:

• issueKey (required): Issue key
• transitionId (required): Transition ID
• comment (optional): Comment to add during transition
• fields (optional): Additional fields to update

Response: Issue PROJ-123 transitioned successfully

Assignments

assign_issue

Assigns an issue to a user.

Parameters:

• issueKey (required): Issue key
• assignee (required): User account ID

Response: Issue PROJ-123 assigned successfully

get_users

Searches for users in Jira.

Parameters:

• query (optional): Search query by name or email
• projectKey (optional): Filter by project access
• maxResults (optional): Max users (1-100, default: 50)

Response: Array of users with essential fields:

[
  {
    "id": "account-id",
    "name": "John Doe",
    "email": "john@example.com",
    "active": true,
    "type": "atlassian"
  }
]

get_current_user

Gets information about the current authenticated user.

Response: Current user with essential fields:

{
  "id": "account-id",
  "name": "Current User",
  "email": "user@example.com",
  "active": true,
  "timezone": "America/New_York",
  "type": "atlassian"
}

Sprint Management

get_agile_boards

Gets all agile boards available in the Jira instance. Required to find board IDs for sprint operations.

Parameters:

• projectKey (optional): Filter boards by project
• boardType (optional): Filter by type (scrum, kanban)

Response: Array of boards with essential fields:

[
  {
    "id": 191,
    "name": "DreamStar Board",
    "type": "scrum",
    "projectKey": "DRMSTR",
    "projectName": "DreamStar"
  }
]

get_sprints

Gets all sprints for a specific board. Returns sprint information including ID, name, state, and dates.

Parameters:

• boardId (required): The ID of the board to get sprints from
• state (optional): Filter sprints by state (active, closed, future)

Response: Array of sprints with essential fields:

[
  {
    "id": 387,
    "name": "DRMSTR Sprint 1",
    "state": "active",
    "startDate": "2025-09-15T14:05:37.511Z",
    "endDate": "2025-09-26T05:00:00.000Z",
    "goal": ""
  }
]

create_sprint

Creates a new sprint. Sprint name and origin board ID are required. Start date, end date, and goal are optional.

Parameters:

• name (required): Name of the sprint to create
• originBoardId (required): ID of the board where the sprint will be created
• startDate (optional): Start date of the sprint (ISO 8601 format)
• endDate (optional): End date of the sprint (ISO 8601 format)
• goal (optional): Goal or objective of the sprint

Response: Created sprint with essential fields:

{
  "id": 421,
  "name": "DRMSTR Sprint 3",
  "state": "future",
  "goal": ""
}

update_sprint

Updates sprint information (name, dates, goal, state). Only provided fields will be updated. For closed sprints, only name and goal can be updated.

Parameters:

• sprintId (required): ID of the sprint to update
• name (optional): New name for the sprint
• startDate (optional): New start date (ISO 8601 format)
• endDate (optional): New end date (ISO 8601 format)
• goal (optional): New goal or objective for the sprint
• state (optional): New state (future, active, closed)

Response: Sprint 421 updated successfully

close_sprint

Closes and completes a sprint. This action requires the sprint to be in the "active" state. Once closed, the sprint cannot be reopened.

Parameters:

• sprintId (required): ID of the sprint to close

Response: Sprint 421 closed successfully

delete_sprint

Deletes a sprint. Once deleted, all open issues in the sprint will be moved to the backlog. This action is irreversible.

Parameters:

• sprintId (required): ID of the sprint to delete

Response: Sprint 421 deleted successfully. All open issues moved to backlog.

move_issue_to_sprint

Moves an issue to a specific sprint. Returns a confirmation message. Issues can only be moved to open or active sprints.

Parameters:

• issueKey (required): Key of the issue to move (e.g., "PROJ-123")
• sprintId (required): ID of the sprint to move the issue to

Response: Issue PROJ-123 moved to sprint 421 successfully

get_sprint_issues

Gets all issues for a given sprint. Returns a list of essential issue details (key, summary, status, assignee, priority).

Parameters:

• sprintId (required): ID of the sprint
• maxResults (optional): Maximum number of issues to return (1-100, default: 50)

Response: Array of issues with essential fields:

[
  {
    "key": "DRMSTR-1",
    "summary": "Implement user authentication",
    "status": "In Progress",
    "assignee": "John Doe",
    "priority": "High"
  }
]

Response Optimization

The server is optimized for token efficiency:

• Essential Fields Only: Returns only necessary fields for each operation
• Custom Fields Filtered: Automatically removes custom fields from issue responses
• Short Field Names: Uses abbreviated field names (e.g., desc instead of description)
• Success Messages: Clear, concise success confirmations
• Structured Data: Consistent response formats across all tools

Error Handling

The server includes robust error handling with descriptive messages. Common errors include:

• Authentication: Invalid or expired credentials
• Permissions: Insufficient permissions for the operation
• Validation: Invalid input data
• Resources: Issues or projects not found
• API: Rate limits or Jira server errors

Development

Project Structure

src/
├── index.ts

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [raalarcon9705](https://github.com/raalarcon9705)
- **Source:** [raalarcon9705/jira-mcp](https://github.com/raalarcon9705/jira-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.