Atlassian MCP Server

Model Context Protocol server for Atlassian Jira operations using the Atlassian CLI (acli) running locally, on your machine, completely private.

Local vs Remote MCP

This is a local stdio MCP server that runs on your machine. For comparison with Atlassian's official solution:

| Feature | This MCP (@teolin/mcp-atlassian) | Atlassian Remote MCP Server | | ------------------------ | ------------------------------------- | ------------------------------------ | | Type | Local stdio server | Remote HTTP server (cloud-hosted) | | Authentication | Atlassian CLI + API token | OAuth | | Scope | Jira only | Jira + Confluence | | Setup | Install npm package + configure CLI | OAuth setup via Atlassian portal | | Access | Personal (your machine) | Team-wide (enterprise) | | Performance | Fast (local, no network latency) | Network-dependent | | Features | Ticket info, extraction, browser open | Bulk operations, enterprise security |

Use this MCP if: You want a lightweight, local solution for Jira ticket operations Use Atlassian's Remote MCP if: You need enterprise features, Confluence access, or team-wide deployment

Features

• Jira Ticket Information: Retrieve ticket details including summary, description, and acceptance criteria
• Ticket Extraction: Automatically extract Jira ticket keys from text (PR titles, branch names, etc.)
• Browser Integration: Opens tickets in your default browser for quick access
• Auto-Authentication: Attempts to authenticate using credentials from .env file
• CLI Integration: Uses Atlassian CLI for seamless Jira access

Prerequisites

• Node.js >=25.2.1
• Atlassian CLI (acli) installed and authenticated
• Jira instance URL

Installation

Option 1: Install from npm (Recommended)

npm install -g @teolin/mcp-atlassian

Option 2: Install locally

npm install @teolin/mcp-atlassian

Option 3: Use with npx (no installation)

npx -y @teolin/mcp-atlassian

Setup

1. Install Atlassian CLI

# Install via npm
npm install -g @atlassian/forge-cli

# Or download from:
# https://developer.atlassian.com/console/install/

2. Install Dependencies

npm install

3. Configure Environment

cp .env.example .env

Edit .env and set:

• JIRA_BASE_URL: Your Jira instance URL (e.g., https://your-domain.atlassian.net)
• JIRA_SITE: Your Jira site domain (e.g., your-domain.atlassian.net)
• JIRA_EMAIL: Your Atlassian account email
• JIRA_API_TOKEN: Your Atlassian API token (Create one here)

4. Authenticate (if not using auto-auth)

acli jira auth login --url https://your-domain.atlassian.net

Usage

Starting the Server

npm start
# or
./start-mcp.sh

Running Tests

npm test

Available Tools

1. jira_ticket_info

Get detailed information about a Jira ticket.

Parameters:

• ticket_key (string, required): Jira ticket key (e.g., "PAB-2197")
• working_directory (string, optional): Working directory path

Features:

• Retrieves ticket details via Atlassian CLI
• Extracts acceptance criteria from ticket description
• Automatically opens ticket in browser
• Falls back gracefully if CLI fails

2. jira_extract_ticket_from_text

Extract Jira ticket key from text.

Parameters:

• text (string, required): Text to search for ticket key

Examples:

• Branch name: feat/PAB-123-description → PAB-123
• PR title: [ABC-456] Fix bug → ABC-456

3. jira_open_ticket

Open a Jira ticket in the default browser.

Parameters:

• ticket_key (string, required): Jira ticket key to open

4. jira_auth_status

Check Atlassian CLI authentication status.

Auto-Authentication

The server attempts to authenticate automatically using .env credentials if the Atlassian CLI is not already authenticated. This provides a seamless experience without manual CLI authentication.

Integration with Claude Code

Claude Code supports three scopes for MCP server configuration:

• User scope (~/.claude.json): Available across all projects
• Local scope (~/.claude.json): Project-specific, private to you (default)
• Project scope (.mcp.json in project root): Team-shared, committed to git

Quick Setup with CLI (Recommended)

# User scope (available in all projects)
claude mcp add atlassian --scope user

# Project scope (shared with team via git)
claude mcp add atlassian --scope project

Manual Configuration

Using npx (Recommended - no installation needed)

Add to .mcp.json (project scope) or ~/.claude.json (user scope):

{
  "mcpServers": {
    "atlassian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@teolin/mcp-atlassian"]
    }
  }
}

Using global installation

{
  "mcpServers": {
    "atlassian": {
      "type": "stdio",
      "command": "atlassian-mcp"
    }
  }
}

Using local installation

{
  "mcpServers": {
    "atlassian": {
      "type": "stdio",
      "command": "node",
      "args": [
        "./node_modules/@teolin/mcp-atlassian/src/index.js"
      ]
    }
  }
}

Using monorepo clone

{
  "mcpServers": {
    "atlassian": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "/path/to/multi-llm-mcps/mcps/Atlassian/start-mcp.sh"
      ]
    }
  }
}

Ticket Key Pattern

The server recognizes Jira ticket keys in the format: [A-Z]+-\d+

Examples: PAB-123, PROJ-456, ABC-789

Troubleshooting

Atlassian CLI not authenticated

acli jira auth status
# If not authenticated:
acli jira auth login --url https://your-domain.atlassian.net

Auto-authentication fails

• Verify .env file contains correct credentials
• Check that JIRA_SITE, JIRA_EMAIL, and JIRA_API_TOKEN are set
• Try manual authentication with acli jira auth login

Browser doesn't open

• Check that JIRA_BASE_URL is correctly set in .env
• Ensure open command is available on your system

Publishing

Using GitHub Actions (Recommended)

This package uses GitHub Actions for automated publishing. To publish a new version:

1. Go to GitHub Actions → "Publish @teolin/mcp-atlassian" → Run workflow
2. The workflow will automatically:
   • Install dependencies
   • Run the prepublishOnly script to make the bin executable
   • Publish to npm with public access

Manual Publishing

Prerequisites

1. You need an npm account: https://www.npmjs.com/signup
2. Login to npm:

   npm login

Publishing Steps

1. Test the package locally (optional but recommended):

   # Test that it runs
   node src/index.js --help
   
   # Or test with environment variables
   JIRA_BASE_URL=https://your-instance.atlassian.net node src/index.js

2. Publish to npm:

   npm publish

   This will:

   • Run the prepublishOnly script to make the bin executable
   • Only include files specified in the files field
   • Publish to npm with public access (configured in publishConfig)

3. Verify the package:

   # Test with npx (no installation)
   npx -y @teolin/mcp-atlassian
   
   # Or install globally and test
   npm install -g @teolin/mcp-atlassian
   atlassian-mcp

Updating the Package

1. Update the version in package.json:

   npm version patch  # for bug fixes (2.0.2 -> 2.0.3)
   npm version minor  # for new features (2.0.2 -> 2.1.0)
   npm version major  # for breaking changes (2.0.2 -> 3.0.0)

2. Publish the new version:

   npm publish

Checking Published Package

View your package on npm:

• https://www.npmjs.com/package/@teolin/mcp-atlassian

Check what files will be included before publishing:

npm pack --dry-run

Troubleshooting

"You do not have permission to publish"

• Make sure you're logged in: npm whoami
• For scoped packages (@teolin/...), ensure you have access to the @teolin organization or use your own scope

"Package name already exists"

• The package name might be taken. Check: https://www.npmjs.com/package/@teolin/mcp-atlassian
• If needed, change the name in package.json

Files missing after installation

• Check the files field in package.json
• Use npm pack --dry-run to preview what will be included

Requirements

• Node.js >=25.2.1
• Atlassian CLI (acli) authenticated
• Network access to Jira instance
• Published on npm: @teolin/mcp-atlassian

License

MIT