# Atlassian MCP Server

A Model Context Protocol (MCP) server for integrating with Atlassian JIRA and Confluence. This server provides tools to interact with JIRA tickets and Confluence pages through the MCP protocol.

![Atlassian MCP Server](./assets/icon.png)

[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-blue.svg)](https://github.com/kompallik/ATLASSIAN-MCP)

## Features

- Get JIRA ticket details
- Search for JIRA tickets using JQL
- Create new JIRA tickets
- Add comments to JIRA tickets
- Get Confluence page content
- Search for content in Confluence

## Prerequisites

- Node.js 16 or higher
- An Atlassian Cloud account
- An Atlassian API token

## Installation

### Option 1: Install from Cline Marketplace (recommended)

1. Open Cline
2. Go to Settings > MCP Servers
3. Select the "Marketplace" tab
4. Search for "Atlassian"
5. Click "Install"
6. Configure your Atlassian credentials when prompted

### Option 2: Install from npm

```bash
npm install -g atlassian-mcp-server
```

### Option 3: Install from source

1. Clone the repository
2. Run the install script:
```bash
./install.sh
```

Or manually:

1. Install dependencies
```bash
npm install
```
2. Build the project
```bash
npm run build
```
3. Install globally
```bash
npm install -g .
```
4. Run the setup
```bash
atlassian-mcp-setup
```

## Configuration

You can configure the server using the setup script, a configuration file, or environment variables.

### Using the setup script (recommended)

Run the setup script to create your configuration file:

```bash
npx atlassian-mcp-setup
```

Or if installed locally:

```bash
npm run setup
```

The script will guide you through the configuration process and create a `config.json` file in the `config` directory.

### Using a configuration file manually

1. Create a `config.json` file in the `config` directory (you can copy from `config.sample.json`)
2. Fill in your Atlassian details:

```json
{
  "atlassian": {
    "baseUrl": "https://your-instance.atlassian.net",
    "email": "your-email@example.com",
    "token": "your-api-token-here"
  },
  "server": {
    "name": "atlassian-server",
    "version": "0.1.0"
  }
}
```

### Using environment variables

Set the following environment variables:

- `ATLASSIAN_BASE_URL`: Your Atlassian instance URL (e.g., `https://your-instance.atlassian.net`)
- `ATLASSIAN_EMAIL`: Your Atlassian account email
- `ATLASSIAN_TOKEN`: Your Atlassian API token
- `ATLASSIAN_CONFIG_PATH`: (Optional) Path to a custom config file location

## Getting an Atlassian API Token

1. Log in to your Atlassian account at https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give your token a name (e.g., "MCP Server")
4. Copy the generated token (you won't be able to see it again)

## Usage

### Running the server

```bash
atlassian-mcp-server
```

Or if installed from source:

```bash
npm start
```

### Integrating with Cline

#### Option 1: Install from Marketplace (recommended)

1. Open Cline
2. Go to Settings > MCP Servers
3. Select the "Marketplace" tab
4. Search for "Atlassian"
5. Click "Install"
6. Configure your Atlassian credentials when prompted

#### Option 2: Manual Configuration

If you've installed the server manually, add the following to your MCP settings:

```json
{
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "args": [],
      "env": {
        "ATLASSIAN_CONFIG_PATH": "/path/to/your/config.json"
      },
      "disabled": false
    }
  }
}
```

Alternatively, you can provide the credentials directly in the settings:

```json
{
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "args": [],
      "env": {
        "ATLASSIAN_BASE_URL": "https://your-instance.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_TOKEN": "your-api-token-here"
      },
      "disabled": false
    }
  }
}
```

## Available Tools

### get_jira_ticket

Get details of a JIRA ticket by key.

Parameters:
- `ticket_key`: JIRA ticket key (e.g., "PROJ-123")

### search_jira_tickets

Search for JIRA tickets using JQL.

Parameters:
- `jql`: JQL query string
- `max_results`: Maximum number of results to return (default: 10)

### create_jira_ticket

Create a new JIRA ticket.

Parameters:
- `project_key`: Project key (e.g., "PROJ")
- `summary`: Ticket summary/title
- `description`: Ticket description
- `issue_type`: Issue type (e.g., "Bug", "Task", "Story") (default: "Task")

### add_comment_to_jira_ticket

Add a comment to a JIRA ticket.

Parameters:
- `ticket_key`: JIRA ticket key (e.g., "PROJ-123")
- `comment`: Comment text

### get_confluence_page

Get a Confluence page by ID.

Parameters:
- `page_id`: Confluence page ID

### search_confluence

Search for content in Confluence.

Parameters:
- `query`: Search query
- `limit`: Maximum number of results (default: 10)

## Publishing to the Marketplace

This server is configured to be published to the Cline MCP Marketplace using the GitHub repository at:
[https://github.com/kompallik/ATLASSIAN-MCP](https://github.com/kompallik/ATLASSIAN-MCP)

To publish updates:

1. Push your changes to the GitHub repository using the provided script:

```bash
npm run push-github
```

2. Add an `icon.png` file in the `assets` directory if not already present
3. Run the publish script:

```bash
npm run publish-mcp
```

4. Follow the prompts to publish to npm and/or create a distribution package
5. Submit your repository URL to the Cline MCP Marketplace team

## License

MIT