Atlassian MCP Server

Speak to Jira and Confluence in natural language to get information on and modify your projects and documentation. Use it with Claude Desktop in combination with a custom README that you will create with project information, so that you can delegate PM tasks, (e.g. given you have a list of my team and their specialities, assign any new issue to the most relevant person).

Built using the Model Context Protocol.

The server enables:

• Project creation and configuration
• Issue and subtask management
• Issue linking and dependencies
• Automated issue workflows
• Confluence page management (search, create, update, delete)
• Comments, labels, and attachments on Confluence pages
• Confluence space and page tree navigation

Configuration

Required environment variables:

• JIRA_HOST: Your Jira instance hostname
• JIRA_PASSWORD: Password for basic auth (falls back to JIRA_API_TOKEN for backward compat)
• JIRA_AUTH_TYPE: Authentication type - either "basic" (default) or "pat"

Optional environment variables:

• JIRA_API_VERSION: Jira API version to use (default: "2" for Jira Server)

For Basic Authentication (default, Jira Server 7.9.2):

• JIRA_USERNAME: Your Jira username (falls back to JIRA_EMAIL for backward compat)

For Personal Access Token (PAT) Authentication:

• Set JIRA_AUTH_TYPE=pat and provide your PAT as JIRA_PASSWORD (or JIRA_API_TOKEN)
• JIRA_USERNAME is not required when using PAT

Personal Access Token Setup

Personal Access Tokens (PATs) are supported on Jira Server / Data Center 7.x+. To create a PAT:

1. Go to your Jira instance settings
2. Navigate to Personal Access Tokens (usually under Security or Account Settings)
3. Click Create token
4. Give your token a descriptive name (e.g., "Jira MCP Server")
5. Set appropriate scopes/permissions (typically you'll need read and write access to projects and issues)
6. Copy the generated token and use it as your JIRA_PASSWORD with JIRA_AUTH_TYPE=pat
7. Set JIRA_AUTH_TYPE=pat in your configuration

Note: If your Jira instance doesn't support PATs, use the basic authentication method with your username and password.

Self-Signed Certificate / HTTP

If your Jira Server uses a self-signed certificate, disable SSL verification globally:

NODE_TLS_REJECT_UNAUTHORIZED=0

To use HTTP instead of HTTPS, simply set JIRA_HOST with the http:// prefix (e.g., JIRA_HOST=http://jira.example.com).

Confluence Configuration

Confluence is optional — the server starts if either Jira or Confluence is configured. All Confluence tools are prefixed with confluence_.

Required environment variables (if using Confluence):

• CONFLUENCE_URL: Confluence base URL (e.g., https://your-domain.atlassian.net/wiki for Cloud, or https://confluence.example.com for Server/DC)
• CONFLUENCE_AUTH_TYPE: "basic" (default) or "pat" (bearer/PAT)

For Basic Authentication (Cloud or Server/DC):

• CONFLUENCE_USERNAME: Username/email for basic auth
• CONFLUENCE_PASSWORD: Password for basic auth

For Personal Access Token (Server/DC only):

• Set CONFLUENCE_AUTH_TYPE=pat and provide your token as CONFLUENCE_PASSWORD
• CONFLUENCE_USERNAME is not required when using PAT

Optional environment variables:

• CONFLUENCE_SSL_STRICT: "true" (default) or "false" (for self-signed certs)
• CONFLUENCE_SPACES_FILTER: Comma-separated list of space keys to filter search results

Available Tools

1. User Management

// Get user's account ID by email
{
  email: "[email protected]";
}

2. Issue Type Management

// List all available issue types
// Returns: id, name, description, subtask status
// No parameters required

3. Issue Link Types

// List all available issue link types
// Returns: id, name, inward/outward descriptions
// No parameters required

4. Issue Management

Retrieving Issues

// Get all issues in a project
{
  projectKey: "PROJECT"
}

// Get issues with JQL filtering
{
  projectKey: "PROJECT",
  jql: "status = 'In Progress' AND assignee = currentUser()"
}

// Get issues assigned to user
{
  projectKey: "PROJECT",
  jql: "assignee = '[email protected]' ORDER BY created DESC"
}

Searching Issues (cross-project)

// Search issues across all projects using JQL — no projectKey required
{
  jql: "assignee = currentUser() ORDER BY updated DESC"
}

// Search by status across all projects
{
  jql: "status = Open AND priority = High",
  maxResults: 50
}

Creating Issues

// Create a standard issue
{
  projectKey: "PROJECT",
  summary: "Issue title",
  issueType: "Task",  // or "Story", "Bug", etc.
  description: "Detailed description",
  assignee: "accountId",  // from get_user tool
  labels: ["frontend", "urgent"],
  components: ["ui", "api"],
  priority: "High"
}

// Create a subtask
{
  parent: "PROJECT-123",
  projectKey: "PROJECT",
  summary: "Subtask title",
  issueType: "Subtask",
  description: "Subtask details",
  assignee: "accountId"
}

Updating Issues

// Update issue fields
{
  issueKey: "PROJECT-123",
  summary: "Updated title",
  description: "New description",
  assignee: "accountId",
  status: "In Progress",
  priority: "High"
}

Issue Dependencies

// Create issue link
{
  linkType: "Blocks",  // from list_link_types
  inwardIssueKey: "PROJECT-124",  // blocked issue
  outwardIssueKey: "PROJECT-123"  // blocking issue
}

Deleting Issues

// Delete single issue
{
  issueKey: "PROJECT-123"
}

// Delete issue with subtasks
{
  issueKey: "PROJECT-123",
  deleteSubtasks: true
}

// Delete multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124"]
}

Confluence Tools

All Confluence tools are available when CONFLUENCE_URL and authentication are configured. Content is automatically converted between Confluence storage format (XHTML) and Markdown.

Search & Navigation

| Tool | Description | Required Parameters | |---|---|---| | confluence_search | Search content using CQL or simple text | query | | confluence_get_page | Get page by ID, URL, or tiny link (or by title + space) | page_id OR (title + space_key) | | confluence_get_page_children | Get child pages of a page | parent_id | | confluence_get_space_page_tree | Get page hierarchy for a space | space_key | | confluence_get_spaces | List all accessible spaces | (none) | | confluence_search_user | Search for Confluence users | query |

Page Content Management

| Tool | Description | Required Parameters | |---|---|---| | confluence_create_page | Create a new page | space_key, title, content | | confluence_update_page | Update an existing page | page_id, content | | confluence_delete_page | Delete a page | page_id | | confluence_move_page | Move a page to a different parent/space | page_id, target_parent_id or target_space_key | | confluence_get_page_history | Get page version history | page_id | | confluence_get_page_restrictions | Get page view/edit restrictions | page_id |

Comments & Labels

| Tool | Description | Required Parameters | |---|---|---| | confluence_get_comments | Get all comments on a page | page_id | | confluence_add_comment | Add a comment to a page (Markdown) | page_id, body | | confluence_get_labels | Get labels for content | page_id | | confluence_add_label | Add a label to content | page_id, name |

Attachments

| Tool | Description | Required Parameters | |---|---|---| | confluence_get_attachments | List attachments for content | content_id | | confluence_download_attachment | Download an attachment to a local path | download_url, target_path | | confluence_upload_attachment | Upload a file as an attachment | content_id, file_path |

Field Formatting

Description Field

The description field supports markdown-style formatting:

• Use blank lines between paragraphs
• Use "- " for bullet points
• Use "1. " for numbered lists
• Use headers ending with ":" (followed by blank line)

Example:

Task Overview:

This task involves implementing new features:
- Feature A implementation
- Feature B testing

Steps:
1. Design component
2. Implement logic
3. Add tests

Acceptance Criteria:
- All tests passing
- Documentation updated

Error Handling

The server provides detailed error messages for:

• Invalid issue keys
• Missing required fields
• Permission issues
• API rate limits

Setup Instructions

Install from npm (no clone or build needed):

npm install -g @noiceman/atlassian-mcp-server@latest

Or run it on demand with npx -y @noiceman/atlassian-mcp-server@latest in your MCP client config (see Configuring Claude Desktop).

The server reads Jira credentials from environment variables injected by your MCP client — no .env file is required. See Configuration for the full list of variables.

Configuring Claude Desktop

To use this MCP server with Claude Desktop:

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the Jira MCP server to your configuration:

   If you installed via npm (or prefer npx without cloning), use this config:

{
  "mcpServers": {
    "atlassian-mcp-server": {
      "command": "npx",
      "args": ["-y", "@noiceman/atlassian-mcp-server@latest"],
      "env": {
        "JIRA_HOST": "your-jira-instance.atlassian.net",
        "JIRA_USERNAME": "your-username",
        "JIRA_PASSWORD": "your-password",
        "JIRA_AUTH_TYPE": "basic",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your-username",
        "CONFLUENCE_PASSWORD": "your-password",
        "CONFLUENCE_AUTH_TYPE": "basic"
      }
    }
  }
}

For PAT auth, use JIRA_PASSWORD with your token and JIRA_AUTH_TYPE: "pat" (no username needed).

If you cloned the repo locally instead, use the absolute-path configs below:

For Basic Authentication (default):

{
 "mcpServers": {
   "atlassian-mcp-server": {
     "name": "atlassian-mcp-server",
     "command": "/path/to/node",
     "args": ["/path/to/atlassian-mcp-server/build/index.js"],
     "cwd": "/path/to/atlassian-mcp-server",
     "env": {
       "JIRA_HOST": "your-jira-instance.atlassian.net",
       "JIRA_USERNAME": "your-username",
       "JIRA_PASSWORD": "your-password",
       "JIRA_AUTH_TYPE": "basic",
       "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
       "CONFLUENCE_USERNAME": "your-username",
       "CONFLUENCE_PASSWORD": "your-password",
       "CONFLUENCE_AUTH_TYPE": "basic"
     }
   }
 }
}

For Personal Access Token (PAT) Authentication:

{
  "mcpServers": {
    "atlassian-mcp-server": {
      "name": "atlassian-mcp-server",
      "command": "/path/to/node",
      "args": ["/path/to/atlassian-mcp-server/build/index.js"],
      "cwd": "/path/to/atlassian-mcp-server",
      "env": {
        "JIRA_HOST": "your-jira-instance.atlassian.net",
        "JIRA_PASSWORD": "your-personal-access-token",
        "JIRA_AUTH_TYPE": "pat",
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PASSWORD": "your-confluence-pat",
        "CONFLUENCE_AUTH_TYPE": "pat"
      }
     }
   }
 }

Replace /path/to/atlassian-mcp-server with the absolute path to your cloned repository. Replace /path/to/node with the absolute path to your Node.js executable (you can usually find this by running which node or where node in your terminal). Using the direct path to the Node.js executable and the built JavaScript file (build/index.js after running npm run build) is recommended for reliability.

3. Restart Claude Desktop to apply the changes.

Configuring Cursor

To use this Atlassian MCP server with Cursor:

1. Ensure the server is built: Run npm run build in the atlassian-mcp-server directory to create the necessary build/index.js file.

2. Locate or create Cursor's MCP configuration file:

   • For project-specific configuration: .cursor/mcp.json in your project's root directory.
   • For global configuration (all projects): ~/.cursor/mcp.json in your home directory.

3. Add the Atlassian MCP server configuration to mcp.json:

   If you installed via npm (or prefer npx without cloning), use this config:

   {
     "mcpServers": {
       "atlassian-mcp-server": {
         "command": "npx",
         "args": ["-y", "@noiceman/atlassian-mcp-server@latest"],
         "env": {
           "JIRA_HOST": "your-jira-instance.atlassian.net",
           "JIRA_USERNAME": "your-username",
           "JIRA_PASSWORD": "your-password",
           "JIRA_AUTH_TYPE": "basic",
           "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
           "CONFLUENCE_USERNAME": "your-username",
           "CONFLUENCE_PASSWORD": "your-password",
         "CONFLUENCE_AUTH_TYPE": "basic"
         }
       }
     }
   }

   For PAT auth, use JIRA_PASSWORD with your token and JIRA_AUTH_TYPE: "pat" (no username needed).

   If you cloned the repo locally instead, use the absolute-path configs below:

   For Basic Authentication (default):

   {
     "mcpServers": {
       "atlassian-mcp-server": {
         "command": "node", // Or provide the absolute path to your Node.js executable
         "args": [
           "/path/to/your/atlassian-mcp-server/build/index.js" // Absolute path to the server's built index.js
         ],
         "cwd": "/path/to/your/atlassian-mcp-server", // Absolute path to the atlassian-mcp-server directory
         "env": {
          "JIRA_HOST": "your-jira-instance.atlassian.net",
           "JIRA_USERNAME": "your-username", // Your Jira username
           "JIRA_PASSWORD": "your-password", // Your Jira password
           "JIRA_AUTH_TYPE": "basic",
           "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
           "CONFLUENCE_USERNAME": "your-username",
           "CONFLUENCE_PASSWORD": "your-password",
         "CONFLUENCE_AUTH_TYPE": "basic"
         }
       }
       // You can add other MCP server configurations here
     }
   }

   For Personal Access Token (PAT) Authentication:

   {
     "mcpServers": {
       "atlassian-mcp-server": {
         "command": "node", // Or provide the absolute path to your Node.js executable
         "args": [
           "/path/to/your/atlassian-mcp-server/build/index.js" // Absolute path to the server's built index.js
         ],
         "cwd": "/path/to/your/atlassian-mcp-server", // Absolute path to the atlassian-mcp-server directory
         "env": {
           "JIRA_HOST": "your-jira-instance.atlassian.net",
           "JIRA_PASSWORD": "your-personal-access-token", // Your Jira PAT
           "JIRA_AUTH_TYPE": "pat",
           "CONFLUENCE_URL": "https://confluence.example.com",
           "CONFLUENCE_PASSWORD": "your-confluence-pat",
           "CONFLUENCE_AUTH_TYPE": "pat"
         }
       }
       // You can add other MCP server configurations here
     }
   }

   • Replace /path/to/your/atlassian-mcp-server with the correct absolute path to where you cloned the atlassian-mcp-server repository.
   • If node is not in your system's PATH or you prefer an absolute path, replace "node" with the full path to your Node.js executable (e.g., /usr/local/bin/node or C:\Program Files\nodejs\node.exe).
   • Ensure your Jira and Confluence instance details and credentials are correctly filled in the env section.

4. Restart Cursor to apply the changes.

Using Cursor Rules for Jira Context

To make interacting with Jira smoother, you can define your default Jira project and user identifier in Cursor's rules. This helps Cursor's AI understand your context without you needing to specify it in every prompt.

Create or edit your Cursor Rules file (e.g., in your project .cursor/rules.json or global ~/.cursor/rules.json (the exact file and method for rules might vary, check Cursor documentation for "Rules" or "Context Management")). Add entries like:

As an AI assistant, when I am asked about Jira tasks:
- Assume the primary Jira project key is 'YOUR_PROJECT_KEY_HERE'.
- Assume 'my assigned tasks' or tasks assigned to 'me' refer to the Jira user with the email '[email protected]' (or your Jira Account ID).
You can then use these in your JQL queries, for example: project = YOUR_PROJECT_KEY_HERE AND assignee = '[email protected]'.

Replace YOUR_PROJECT_KEY_HERE and [email protected] with your actual details.

Example Usage in Cursor Chat

Once configured (especially with Cursor Rules for context), you can ask Cursor:

"Using Jira MCP, list my assigned tasks. Then, based on these tasks, come up with an implementation plan and work schedule."

The search_issues tool makes this work even without Cursor Rules: it runs assignee = currentUser() across all projects, so you don't need to specify a project key or your email.

If you haven't set up rules, or need to specify a different project or user, you'd be more explicit:

"Using Jira MCP, list tasks assigned to '[email protected]' in project 'PROJECT_KEY'. Then, based on these tasks, come up with an implementation plan and work schedule."

Cursor's AI will use the Atlassian MCP server to fetch the tasks, and then proceed with the planning and scheduling request.

From Source (for development)

Clone and build the repository if you want to modify the server or run unreleased changes:

1. Clone the repository:

   git clone https://github.com/noiceman/atlassian-mcp-server.git
   cd atlassian-mcp-server

2. Install dependencies:

   npm install

3. Configure environment variables: The server reads credentials from process.env directly (no dotenv dependency). For local development, export them in your shell before building/running:

   Basic auth (default):

   export JIRA_HOST=jira.example.com
   export JIRA_USERNAME=your-username
   export JIRA_PASSWORD=your-password
   export JIRA_AUTH_TYPE=basic
   # Confluence (optional)
   export CONFLUENCE_URL=https://your-domain.atlassian.net/wiki
   export CONFLUENCE_USERNAME=your-username
   export CONFLUENCE_PASSWORD=your-password
   export CONFLUENCE_AUTH_TYPE=basic

   Personal Access Token (PAT):

   export JIRA_HOST=jira.example.com
   export JIRA_PASSWORD=your-personal-access-token
   export JIRA_AUTH_TYPE=pat
   # Confluence (optional, PAT for Server/DC)
   export CONFLUENCE_URL=https://confluence.example.com
   export CONFLUENCE_PASSWORD=your-confluence-pat
   export CONFLUENCE_AUTH_TYPE=pat

   Alternatively, set the env block in your MCP client config (see Configuring Claude Desktop).

4. Build the project:

   npm run build

5. Start the server:

   npm start

References

• Model Context Protocol
• Jira REST API Documentation (7.9.2)
• Jira REST API Examples
• Confluence REST API Documentation
• Confluence Cloud API Reference
• Confluence Server/DC API
• Confluence Storage Format