Metadata-Version: 2.4
Name: mcp-atlassian
Version: 0.2.4
Summary: The Model Context Protocol (MCP) Atlassian integration is an open-source implementation that bridges Atlassian products (Jira and Confluence) with AI language models following Anthropic's MCP specification. This project enables secure, contextual AI interactions with Atlassian tools while maintaining data privacy and security. Key features include:
Author-email: sooperset <soomiles.dev@gmail.com>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: atlassian-python-api>=3.41.16
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.28.0
Requires-Dist: markdown-to-confluence>=0.3.0
Requires-Dist: markdown>=3.7.0
Requires-Dist: markdownify>=0.11.6
Requires-Dist: mcp>=1.3.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: starlette>=0.37.1
Requires-Dist: trio>=0.29.0
Requires-Dist: uvicorn>=0.27.1
Description-Content-Type: text/markdown

# MCP Atlassian

Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). This integration supports both Atlassian Cloud and Jira Server/Data Center deployments.

### Feature Demo
![Jira Demo](https://github.com/user-attachments/assets/61573853-c8a8-45c9-be76-575f2b651984)

<details>
<summary>Confluence Demo</summary>

![Confluence Demo](https://github.com/user-attachments/assets/8a203391-795a-474f-8123-9c11f13a780e)
</details>

### Compatibility

| Product | Deployment Type | Support Status              |
|---------|----------------|-----------------------------|
| **Confluence** | Cloud | ✅ Fully supported           |
| **Confluence** | Server/Data Center | ✅ Supported (version 7.9+)  |
| **Jira** | Cloud | ✅ Fully supported           |
| **Jira** | Server/Data Center | ✅ Supported (version 8.14+) |

## Setup Guide

### 1. Authentication Setup

First, generate the necessary authentication tokens:

#### For Atlassian Cloud
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click **Create API token**, name it
3. Copy the token immediately

#### For Server/Data Center
1. Go to your profile (avatar) → **Profile** → **Personal Access Tokens**
2. Click **Create token**, name it, set expiry
3. Copy the token immediately

### 2. Installation

Choose one of these installation methods:

#### Using uv (recommended)
```bash
# Install uv on macOS
brew install uv

# Run directly with uvx
uvx mcp-atlassian
```

#### Using PIP
```bash
pip install mcp-atlassian
```

#### Using Docker
```bash
git clone https://github.com/sooperset/mcp-atlassian.git
cd mcp-atlassian
docker build -t mcp/atlassian .
```

### 3. Configuration

The integration supports using either Confluence, Jira, or both services. You only need to configure the service(s) you want to use.

#### Configuration Variables

**Note:** For all configuration methods, include only the environment variables needed for your services:
- For Confluence Cloud: Include `CONFLUENCE_URL`, `CONFLUENCE_USERNAME`, and `CONFLUENCE_API_TOKEN`
- For Confluence Server/Data Center: Include `CONFLUENCE_URL` and `CONFLUENCE_PERSONAL_TOKEN`
- For Jira Cloud: Include `JIRA_URL`, `JIRA_USERNAME`, and `JIRA_API_TOKEN`
- For Jira Server/Data Center: Include `JIRA_URL` and `JIRA_PERSONAL_TOKEN`
- For SSE transport: Add `--transport sse` and `--port` arguments

<details>
<summary>View all configuration options</summary>

| Setting | Environment Variable | CLI Argument | Cloud | Server/DC |
|---------|-------------------|--------------|:-----:|:---------:|
| **Confluence** |
| URL | `CONFLUENCE_URL` | `--confluence-url` | O | O |
| Email | `CONFLUENCE_USERNAME` | `--confluence-username` | O | X |
| API Token | `CONFLUENCE_API_TOKEN` | `--confluence-token` | O | X |
| PAT | `CONFLUENCE_PERSONAL_TOKEN` | `--confluence-personal-token` | X | O |
| **Jira** |
| URL | `JIRA_URL` | `--jira-url` | O | O |
| Email | `JIRA_USERNAME` | `--jira-username` | O | X |
| API Token | `JIRA_API_TOKEN` | `--jira-token` | O | X |
| PAT | `JIRA_PERSONAL_TOKEN` | `--jira-personal-token` | X | O |
| **Common** |
| SSL Verify | `*_SSL_VERIFY` | `--[no-]*-ssl-verify` | X | Optional |
| Transport | - | `--transport stdio\|sse` | Optional | Optional |
| Port | - | `--port INTEGER` | Required for SSE | Required for SSE |

</details>

#### Quick Start Examples

```bash
# For Cloud (stdio transport)
uvx mcp-atlassian \
  --confluence-url=https://your.atlassian.net/wiki \
  --confluence-username=email \
  --confluence-token=token \
  --jira-url=https://your.atlassian.net \
  --jira-username=email \
  --jira-token=token

# For Server/DC (SSE transport)
uvx mcp-atlassian \
  --confluence-url=https://confluence.company.com \
  --confluence-personal-token=token \
  --jira-url=https://jira.company.com \
  --jira-personal-token=token \
  --transport sse \
  --port 8000
```

### 4. IDE Integration

#### Cursor IDE Setup

1. Open Cursor Settings
2. Navigate to `Features` > `MCP Servers`
3. Click `Add new MCP server`

- For stdio transport, enter the configuration:
   ```yaml
   name: mcp-atlassian
   type: command
   command: uvx mcp-atlassian --confluence-url=https://your-domain.atlassian.net/wiki --confluence-username=email --confluence-token=token --jira-url=https://your-domain.atlassian.net --jira-username=email --jira-token=token
   ```

![Image](https://github.com/user-attachments/assets/41658cb1-a1ab-4724-89f1-a7a00819947a)

- For SSE transport:

   First, start the MCP server in a terminal:
   ```bash
   uvx mcp-atlassian ... --transport sse --port 8000
   ```

   Then configure Cursor to connect to it:
   ```yaml
   name: mcp-atlassian
   type: sse
   Server URL: http://localhost:8000/sse
   ```
   Note: The SSE server must be running before you can connect Cursor to it.

![Image](https://github.com/user-attachments/assets/ff8a911b-d0e9-48cc-b7a1-3d3497743a98)

4. Switch to Agent mode in the Composer to use MCP tools

![image](https://github.com/user-attachments/assets/13c7ba94-d96b-4e40-a00d-13d3bbffe944)

#### Claude Desktop Setup

<details>
<summary>Using uvx</summary>

```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

For Confluence/Jira Server/Data Center:

```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_access_token",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_access_token"
      }
    }
  }
}
```

</details>

<details>
<summary>Using pip</summary>

```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "python",
      "args": ["-m", "mcp-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

</details>

<details>
<summary>Using docker</summary>

There are two ways to configure the Docker environment:

1. Using environment variables directly in the config:
```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mcp/atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

2. Using an environment file:
```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/your/.env",
        "mcp/atlassian"
      ]
    }
  }
}
```

The .env file should contain:
```env
# Confluence Cloud
CONFLUENCE_URL=https://your-domain.atlassian.net/wiki  # Your Confluence cloud URL
CONFLUENCE_USERNAME=your.email@domain.com              # Your Atlassian account email
CONFLUENCE_API_TOKEN=your_api_token                    # API token for Confluence

# Confluence Server/Data Center (alternative to CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN)
# CONFLUENCE_URL=https://confluence.your-company.com        # Your Confluence Server/Data Center URL
# CONFLUENCE_PERSONAL_TOKEN=your_personal_access_token      # Personal Access Token for Confluence Server/Data Center
# CONFLUENCE_SSL_VERIFY=true                                # Set to 'false' for self-signed certificates

# Jira Cloud
JIRA_URL=https://your-domain.atlassian.net            # Your Jira cloud URL
JIRA_USERNAME=your.email@domain.com                   # Your Atlassian account email
JIRA_API_TOKEN=your_api_token                         # API token for Jira Cloud

# Jira Server/Data Center (alternative to JIRA_USERNAME and JIRA_API_TOKEN)
# JIRA_URL=https://jira.your-company.com              # Your Jira Server/Data Center URL
# JIRA_PERSONAL_TOKEN=your_personal_access_token      # Personal Access Token for Jira Server/Data Center
# JIRA_SSL_VERIFY=true                                # Set to 'false' for self-signed certificates
```

</details>

## Resources

> **Note:** The MCP server filters resources to only show Confluence spaces and Jira projects that the user is actively interacting with, based on their contributions and assignments.

- `confluence://{space_key}`: Access Confluence spaces
- `jira://{project_key}`: Access Jira projects

## Available Tools

| Tool | Description |
|------|-------------|
| `confluence_search` | Search Confluence content using CQL |
| `confluence_get_page` | Get content of a specific Confluence page |
| `confluence_get_page_children` | Get child pages of a specific Confluence page |
| `confluence_get_page_ancestors` | Get parent pages of a specific Confluence page |
| `confluence_get_comments` | Get comments for a specific Confluence page |
| `confluence_create_page` | Create a new Confluence page |
| `confluence_update_page` | Update an existing Confluence page |
| `confluence_delete_page` | Delete an existing Confluence page |
| `jira_get_issue` | Get details of a specific Jira issue |
| `jira_search` | Search Jira issues using JQL |
| `jira_get_project_issues` | Get all issues for a specific Jira project |
| `jira_create_issue` | Create a new issue in Jira |
| `jira_update_issue` | Update an existing Jira issue |
| `jira_delete_issue` | Delete an existing Jira issue |
| `jira_get_transitions` | Get available status transitions for a Jira issue |
| `jira_transition_issue` | Transition a Jira issue to a new status |
| `jira_add_worklog` | Add a worklog entry to a Jira issue |
| `jira_get_worklog` | Get worklog entries for a Jira issue |
| `jira_link_to_epic` | Link an issue to an Epic |
| `jira_get_epic_issues` | Get all issues linked to a specific Epic |

## Development & Debugging

### Local Development Setup

If you've cloned the repository and want to run a local version:

```json
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/your/mcp-atlassian",
        "run", "mcp-atlassian",
        "--confluence-url=https://your-domain.atlassian.net/wiki",
        "--confluence-username=your.email@domain.com",
        "--confluence-token=your_api_token",
        "--jira-url=https://your-domain.atlassian.net",
        "--jira-username=your.email@domain.com",
        "--jira-token=your_api_token"
      ]
    }
  }
}
```

### Debugging Tools

- MCP Inspector:
  ```bash
  # For standard installation
  npx @modelcontextprotocol/inspector uvx mcp-atlassian

  # For development installation
  cd path/to/mcp-atlassian
  npx @modelcontextprotocol/inspector uv run mcp-atlassian
  ```

- View logs:
  ```bash
  tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
  ```

## Security

- Never share API tokens
- Keep .env files secure and private
- See [SECURITY.md](SECURITY.md) for best practices

## License

Licensed under MIT - see [LICENSE](LICENSE) file. This is not an official Atlassian product.
