MCP Atlassian Jira Server

A Model Context Protocol (MCP) server for Atlassian Jira integration. This project allows AI assistants like Claude Desktop and Cursor AI to access and interact with Atlassian Jira content through the Model Context Protocol.

Note: This project is forked from boilerplate-mcp-server, a template for building MCP servers. It maintains compatibility with the boilerplate while adding Jira-specific functionality.

Core Features

This MCP server provides the following capabilities:

Atlassian Jira Integration

• Projects Management:

  • list-projects: List all available Jira projects with their IDs, keys, names, and URLs (with filtering options)
  • get-project: Get detailed information about a specific Jira project by ID or key, including metadata, components, and versions

• Issues Management:

  • list-issues: List Jira issues with filtering options by project, status, and more using JQL (Jira Query Language)
  • get-issue: Get detailed information about a specific Jira issue by ID or key, including content, comments, and metadata

• Pagination Support:

  • Cursor-based pagination for projects and issues listings
  • Seamless navigation through large result sets
  • Clear pagination information in the output with instructions for retrieving the next page
  • Support in both CLI commands and MCP tools

Configuration Options for End Users

Before setting up with Claude Desktop or Cursor AI, you'll need to configure your Atlassian credentials. There are two recommended options for end users:

Option 1: Direct Configuration in Claude/Cursor

Pass your Atlassian credentials directly in the Claude Desktop config or Cursor AI command:

{
  "mcpServers": {
    "aashari/mcp-atlassian-jira": {
      "command": "npx",
      "args": ["-y", "DEBUG=true", "ATLASSIAN_SITE_NAME=your_site_name", "ATLASSIAN_USER_EMAIL=your_email", "ATLASSIAN_API_TOKEN=your_token", "aashari/mcp-atlassian-jira"]
    }
  }
}

Option 2: Global Configuration File (Recommended)

1. Create a global configuration file at $HOME/.mcp/configs.json:

{
  "@aashari/mcp-atlassian-jira": {
    "environments": {
      "DEBUG": "true",
      "ATLASSIAN_SITE_NAME": "example",
      "ATLASSIAN_USER_EMAIL": "my.username@example.com",
      "ATLASSIAN_API_TOKEN": "your-atlassian-api-token"
    }
  }
}

2. Then use a simplified configuration in Claude Desktop or Cursor AI:

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

This approach keeps your credentials in one secure location and simplifies your AI assistant configuration.

Required Configuration

• ATLASSIAN_SITE_NAME: Your Atlassian site name (e.g., for https://example.atlassian.net, use example).
• ATLASSIAN_USER_EMAIL: Email address associated with your Atlassian account.
• ATLASSIAN_API_TOKEN: API token for Atlassian API access (create at Atlassian API tokens).

Optional Configuration

• DEBUG: Set to true to enable debug logging.

Setting Up with Claude Desktop

To use this MCP server with Claude Desktop:

1. Open Claude Desktop Settings:

   • Launch Claude Desktop
   • Click on the settings icon (gear) in the top-right corner

   

2. Edit MCP Configuration:

   • Click on "Edit Config" button
   • This will open File Explorer/Finder with the claude_desktop_config.json file

3. Update Configuration File:

   • Add one of the configuration options from above to the file
   • Save the file

   Example with global configuration file already set up:

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

4. Restart Claude Desktop:

   • Close and reopen Claude Desktop to apply the changes

   

5. Verify Tool Availability:

   • On the Claude home page, look for the hammer icon on the right side
   • Click it to see available tools
   • Ensure the tools are listed

   

6. Test the Tool:

   • Try asking Claude to use one of the available tools
   • For example: "List all Jira projects" or "Get details about Jira issue with ID PROJ-123"
   • Claude will use the MCP tool to fetch and display the requested information

Setting Up with Cursor AI

To use this MCP server with Cursor AI:

1. Open Cursor Settings:

   • Launch Cursor
   • Press CMD + SHIFT + P (or CTRL + SHIFT + P on Windows)
   • Type "settings" and select "Cursor Settings"
   • On the sidebar, select "MCP"

   

2. Add New MCP Server:

   • Click "+ Add new MCP server"
   • A configuration form will appear

   

3. Configure MCP Server:

   • Name: Enter aashari/mcp-atlassian-jira
   • Type: Select command from the dropdown
   • Command: Choose one of the following based on your configuration approach:

   If using global configuration file (recommended):

   npx -y aashari/mcp-atlassian-jira
   

   If passing credentials directly:

   DEBUG=true ATLASSIAN_SITE_NAME=your_site_name ATLASSIAN_USER_EMAIL=your_email ATLASSIAN_API_TOKEN=your_token npx -y aashari/mcp-atlassian-jira
   

   • Click "Add"

4. Verify Server Configuration:

   • The server should now be listed with a green indicator
   • You should see the available tools listed under the server

   

5. Test the Tool:

   • In the chat sidebar, ensure Agent mode is active
   • Try asking Cursor AI to use one of the available tools
   • For example: "List all Jira projects" or "Get details about Jira issue with ID PROJ-123"
   • Cursor AI will use the MCP tool to fetch and display the requested information

Using as a CLI Tool

The package can also be used as a command-line tool for human interaction:

• Get help and available commands:

  npx -y aashari/mcp-atlassian-jira --help
  

  Example output:

  Usage: @aashari/mcp-atlassian-jira [options] [command]
  
  A Model Context Protocol (MCP) server for Atlassian Jira integration
  
  Options:
    -V, --version               output the version number
    -h, --help                  display help for command
  
  Commands:
    list-projects [options]     List Jira projects with optional filtering
    get-project <idOrKey>       Get detailed information about a specific Jira project
    list-issues [options]       List Jira issues with optional filtering
    get-issue <idOrKey>         Get detailed information about a specific Jira issue
    help [command]              display help for command
  

Projects Commands

• List Jira projects:

  npx -y aashari/mcp-atlassian-jira list-projects
  

  With filtering options:

  npx -y aashari/mcp-atlassian-jira list-projects --query "Marketing" --limit 5
  

  With pagination:

  npx -y aashari/mcp-atlassian-jira list-projects --cursor 5
  

• Get project details:

  npx -y aashari/mcp-atlassian-jira get-project PROJ
  

  Example output:

  # Project: Marketing Website (PROJ)
  
  **Key**: PROJ
  **Name**: Marketing Website
  **Type**: Business
  **Style**: Next-gen
  **Lead**: John Doe
  
  ## Description
  This project manages all tasks related to our marketing website redesign and maintenance.
  
  ## URLs
  - **Self**: https://example.atlassian.net/rest/api/3/project/10001
  - **Web**: https://example.atlassian.net/browse/PROJ
  
  ## Components
  1. **Frontend** - Website frontend components
  2. **Backend** - API and server components
  3. **Content** - Marketing copy and assets
  
  ## Versions
  1. **v1.0** - Initial Release (Released: 2023-01-15)
  2. **v1.1** - Bug fixes (Released: 2023-02-28)
  3. **v2.0** - Major redesign (Unreleased)
  

Issues Commands

• List Jira issues:

  npx -y aashari/mcp-atlassian-jira list-issues
  

  With JQL filtering:

  npx -y aashari/mcp-atlassian-jira list-issues --jql "project = PROJ AND status = 'In Progress'"
  

  With pagination:

  npx -y aashari/mcp-atlassian-jira list-issues --limit 10 --cursor 10
  

• Get issue details:

  npx -y aashari/mcp-atlassian-jira get-issue PROJ-123
  

  Example output:

  # PROJ-123: Implement new homepage design
  
  **Key**: PROJ-123
  **Type**: Task
  **Status**: In Progress
  **Priority**: Medium
  **Assignee**: Jane Smith
  **Reporter**: John Doe
  **Created**: 2023-03-15T10:30:45.000Z
  **Updated**: 2023-03-20T14:22:33.000Z
  
  ## Description
  We need to implement the new homepage design according to the mockups provided by the design team.
  
  The new design includes:
  - Hero section with animated banner
  - Product showcase with carousel
  - Customer testimonials section
  - Updated footer with social media links
  
  ## Comments
  1. **John Doe** (2023-03-15):
     Initial task creation with requirements
  
  2. **Jane Smith** (2023-03-18):
     Started implementation, hero section complete
  
  ## Attachments
  - homepage-mockup.png (2.3 MB)
  - design-specs.pdf (1.1 MB)
  
  ## Links
  - **Web**: https://example.atlassian.net/browse/PROJ-123
  - **Self**: https://example.atlassian.net/rest/api/3/issue/10123
  

Development

For information on developing and contributing to this project, please see the DEVELOPMENT.md file.

License

ISC

Author

Andi Ashari