Metadata-Version: 2.4
Name: atlassian-hub
Version: 0.2.0
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>=4.0.0
Requires-Dist: authlib<1.7.0,>=1.6.12
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: cachetools>=5.0.0
Requires-Dist: click>=8.1.7
Requires-Dist: cryptography>=46.0.7
Requires-Dist: fakeredis<2.35.0,>=2.32.1
Requires-Dist: fastmcp<4.0.0,>=3.2.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: idna>=3.15
Requires-Dist: keyring>=25.6.0
Requires-Dist: lxml>=6.1.0
Requires-Dist: markdown-to-confluence<0.4.0,>=0.3.4
Requires-Dist: markdown>=3.7.0
Requires-Dist: markdownify>=0.11.6
Requires-Dist: mcp<2.0.0,>=1.8.0
Requires-Dist: pydantic<3.0,>=2.10.6
Requires-Dist: pygments>=2.20.0
Requires-Dist: pyjwt>=2.12.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: python-multipart>=0.0.27
Requires-Dist: requests[socks]>=2.33.0
Requires-Dist: starlette>=1.0.1
Requires-Dist: thefuzz>=0.22.1
Requires-Dist: trio>=0.29.0
Requires-Dist: truststore>=0.10.0
Requires-Dist: types-cachetools>=5.5.0.20240820
Requires-Dist: types-python-dateutil>=2.9.0.20241206
Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
Requires-Dist: unidecode>=1.3.0
Requires-Dist: urllib3>=2.7.0
Requires-Dist: uvicorn>=0.27.1
Description-Content-Type: text/markdown

# MCP Atlassian

![PyPI Version](https://img.shields.io/pypi/v/atlassian-hub)
![PyPI - Downloads](https://img.shields.io/pypi/dm/atlassian-hub)
![PePy - Total Downloads](https://static.pepy.tech/personalized-badge/atlassian-hub?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Total%20Downloads)
[![Run Tests](https://github.com/Raviguntakala/atlassian-hub/actions/workflows/tests.yml/badge.svg)](https://github.com/Raviguntakala/atlassian-hub/actions/workflows/tests.yml)
![License](https://img.shields.io/github/license/Raviguntakala/atlassian-hub)
[![Docs](https://img.shields.io/badge/docs-mintlify-blue)](https://mcp-atlassian.soomiles.com)

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

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

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

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

</details>

## Quick Start

### 1. Get Your API Token

Go to https://id.atlassian.com/manage-profile/security/api-tokens and create a token.

> For Server/Data Center, use a Personal Access Token instead. See [Authentication](https://mcp-atlassian.soomiles.com/docs/authentication).

### 2. Configure Your Client

Add `atlassian-hub` to your MCP client. Pick the tab matching your setup — the env block is the same across all of them, only the surrounding config format differs.

**Claude Desktop / Cursor** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

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

<details>
<summary><b>Claude Code</b> (Anthropic CLI)</summary>

One-liner via the `claude mcp` command:

```bash
claude mcp add atlassian-hub uvx atlassian-hub \
  -e JIRA_URL=https://your-company.atlassian.net \
  -e JIRA_USERNAME=your.email@company.com \
  -e JIRA_API_TOKEN=your_api_token \
  -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki \
  -e CONFLUENCE_USERNAME=your.email@company.com \
  -e CONFLUENCE_API_TOKEN=your_api_token
```

Or edit `~/.claude.json` (user-scope) / `.mcp.json` (project-scope) with the same JSON shape as the Claude Desktop example above.

</details>

<details>
<summary><b>Codex</b> (OpenAI CLI)</summary>

Edit `~/.codex/config.toml`:

```toml
[mcp_servers.atlassian-hub]
command = "uvx"
args = ["atlassian-hub"]

[mcp_servers.atlassian-hub.env]
JIRA_URL = "https://your-company.atlassian.net"
JIRA_USERNAME = "your.email@company.com"
JIRA_API_TOKEN = "your_api_token"
CONFLUENCE_URL = "https://your-company.atlassian.net/wiki"
CONFLUENCE_USERNAME = "your.email@company.com"
CONFLUENCE_API_TOKEN = "your_api_token"
```

</details>

<details>
<summary><b>GitHub Copilot</b> (VS Code MCP)</summary>

Create `.vscode/mcp.json` in your workspace (or add under `"mcp.servers"` in VS Code settings):

```json
{
  "servers": {
    "atlassian-hub": {
      "type": "stdio",
      "command": "uvx",
      "args": ["atlassian-hub"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

For secrets, prefer `${input:jira_token}` placeholders with `inputs[].type = "promptString"` rather than committing tokens to the file.

</details>

<details>
<summary><b>opencode</b></summary>

Edit `opencode.json` (project-scope) or `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian-hub": {
      "type": "local",
      "command": ["uvx", "atlassian-hub"],
      "enabled": true,
      "environment": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

</details>

> **Server/Data Center users**: Use `JIRA_PERSONAL_TOKEN` instead of `JIRA_USERNAME` + `JIRA_API_TOKEN`. See [Authentication](https://mcp-atlassian.soomiles.com/docs/authentication) for details.

### 3. Start Using

Ask your AI assistant to:
- **"Find issues assigned to me in PROJ project"**
- **"Search Confluence for onboarding docs"**
- **"Create a bug ticket for the login issue"**
- **"Update the status of PROJ-123 to Done"**

## Documentation

Full documentation is available at **[mcp-atlassian.soomiles.com](https://mcp-atlassian.soomiles.com)**.

> **Note:** The docs site covers the original `mcp-atlassian` package. Everything applies equally to `atlassian-hub` — wherever you see `mcp-atlassian` in installation or configuration examples, substitute `atlassian-hub`.

Documentation is also available in [llms.txt format](https://llmstxt.org/), which LLMs can consume easily:
- [`llms.txt`](https://mcp-atlassian.soomiles.com/llms.txt) — documentation sitemap
- [`llms-full.txt`](https://mcp-atlassian.soomiles.com/llms-full.txt) — complete documentation

| Topic | Description |
|-------|-------------|
| [Installation](https://mcp-atlassian.soomiles.com/docs/installation) | uvx, Docker, pip, from source |
| [Authentication](https://mcp-atlassian.soomiles.com/docs/authentication) | API tokens, PAT, OAuth 2.0 |
| [Configuration](https://mcp-atlassian.soomiles.com/docs/configuration) | IDE setup, environment variables |
| [HTTP Transport](https://mcp-atlassian.soomiles.com/docs/http-transport) | SSE, streamable-http, multi-user |
| [Tools Reference](https://mcp-atlassian.soomiles.com/docs/tools-reference) | All Jira & Confluence tools |
| [Troubleshooting](https://mcp-atlassian.soomiles.com/docs/troubleshooting) | Common issues & debugging |

## Compatibility

| Product | Deployment | Support |
|---------|------------|---------|
| Confluence | Cloud | Fully supported |
| Confluence | Server/Data Center | Supported (v6.0+) |
| Jira | Cloud | Fully supported |
| Jira | Server/Data Center | Supported (v8.14+) |

## Key Tools

| Jira | Confluence |
|------|------------|
| `jira_search` - Search with JQL | `confluence_search` - Search with CQL |
| `jira_get_issue` - Get issue details | `confluence_get_page` - Get page content |
| `jira_create_issue` - Create issues | `confluence_create_page` - Create pages |
| `jira_update_issue` - Update issues | `confluence_update_page` - Update pages |
| `jira_transition_issue` - Change status | `confluence_add_comment` - Add comments |

**72 tools across 21 toolsets** — by default only the 6 core toolsets (~23 tools) are enabled to keep the AI assistant's context lean. Set `TOOLSETS=all` to enable everything, or `TOOLSETS=default,jira_agile` to add specific extras. See [Tools Reference](https://mcp-atlassian.soomiles.com/docs/tools-reference) for the full list.

## Security

Never share API tokens. Keep `.env` files secure. See [SECURITY.md](SECURITY.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and the full **release & PyPI publish process** (versioning via git tags, `uv build`, `uvx uv-publish`).

## License

MIT - See [LICENSE](LICENSE). Not an official Atlassian product.
