# Jira Mcp

> Open source MCP server for Jira & Atlassian — manage issues, sprints & Confluence via Claude, Cursor, or any MCP client. No install, just npx.

- **Type:** MCP server
- **Install:** `agentstack add mcp-raalarcon9705-jira-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raalarcon9705](https://agentstack.voostack.com/s/raalarcon9705)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [raalarcon9705](https://github.com/raalarcon9705)
- **Source:** https://github.com/raalarcon9705/jira-mcp

## Install

```sh
agentstack add mcp-raalarcon9705-jira-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)](https://modelcontextprotocol.io/) 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.

```json
{
  "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](https://claude.ai/download) | ✅ |
| [Claude Code](https://claude.ai/code) | ✅ |
| [Cursor](https://cursor.sh) | ✅ |
| [Windsurf](https://codeium.com/windsurf) | ✅ |
| [Cline](https://github.com/cline/cline) | ✅ |
| [Continue](https://continue.dev) | ✅ |
| 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](https://mcpmarket.com/) — MCP server marketplace
- [MCP Servers](https://mcpservers.org/) — Awesome MCP Servers directory
- [Claude Marketplaces](https://claudemarketplaces.com) — Claude plugins & MCP directory
- [npm](https://www.npmjs.com/package/raalarcon-jira-mcp-server) — `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:

```json
{
  "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"
      }
    }
  }
}
```

2. **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**:

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

2. **Install dependencies**:

```bash
npm install
```

3. **Build the project**:

```bash
npm run build
```

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

```json
{
  "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](https://id.atlassian.com/manage-profile/security/api-tokens)
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

```javascript
// 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

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Testing with npx

You can also test the server directly with npx:

```bash
# 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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
{
  "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
{
  "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
{
  "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:

```json
[
  {
    "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-raalarcon9705-jira-mcp
- Seller: https://agentstack.voostack.com/s/raalarcon9705
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.