Metadata-Version: 2.4
Name: bcs-mcp-atlassian
Version: 0.0.1.dev556
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: beautifulsoup4>=4.12.3
Requires-Dist: cachetools>=5.0.0
Requires-Dist: click>=8.1.7
Requires-Dist: fastmcp<2.15.0,>=2.13.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=25.6.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: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: requests[socks]>=2.31.0
Requires-Dist: starlette>=0.49.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.6.3
Requires-Dist: uvicorn>=0.27.1
Description-Content-Type: text/markdown

# MCP Atlassian

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

Confluence Demo

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

## 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://bcs-mcp-atlassian.soomiles.com/docs/authentication).

### 2. Configure Your IDE

Add to your Claude Desktop or Cursor MCP configuration:

```json
{
  "mcpServers": {
    "bcs-mcp-atlassian": {
      "command": "uvx",
      "args": ["bcs-mcp-atlassian"],
      "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"
      }
    }
  }
}
```

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

**Optional — content masking**: To send Jira/Confluence text content through an external mask/verification service before returning it to the client, set `CONTENT_MASK_SERVICE_URL` to the service endpoint (e.g. `https://apis.tusvc.bcs.ru/mai-ms-masking-it-proxy/mask/chat`). If unset, content is returned as-is.

**Optional — log file**: To write server logs to a file (e.g. to view them in Cursor when the MCP client panel does not show server stderr), set `MCP_LOG_FILE` to a file path (e.g. `bcs-mcp-atlassian.log`). Logs are appended to the file in UTF-8.

**Running with local code (e.g. in Cursor)**: To avoid "program not found" when Cursor spawns the process (wrong working directory or `uv` not in PATH), use the wrapper script as `command` with the **full path** to this repo:

```json
"bcs-mcp-atlassian": {
  "command": "C:\\Users\\Anton\\Downloads\\atlassian\\bcs-mcp-atlassian-bcs\\run-bcs-mcp-atlassian.bat",
  "args": [],
  "env": {
    "JIRA_URL": "https://jira.bcs.ru",
    "JIRA_PERSONAL_TOKEN": "<your-token>",
    "CONFLUENCE_URL": "https://confluence.bcs.ru",
    "CONFLUENCE_PERSONAL_TOKEN": "<your-token>",
    "CONTENT_MASK_SERVICE_URL": "https://apis.tusvc.bcs.ru/mai-ms-masking-it-proxy/mask/chat"
  }
}
```

Replace the path with your actual clone path. The script [run-bcs-mcp-atlassian.bat](run-bcs-mcp-atlassian.bat) switches to the project directory and runs `uv run bcs-mcp-atlassian` there. If your workspace root is this folder and `uv` is in PATH, you can instead use `"command": "uv"` and `"args": ["run", "bcs-mcp-atlassian"]`.

### 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 **[bcs-mcp-atlassian.soomiles.com](https://bcs-mcp-atlassian.soomiles.com)**.

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

| Topic | Description |
|-------|-------------|
| [Installation](https://bcs-mcp-atlassian.soomiles.com/docs/installation) | uvx, Docker, pip, from source |
| [Authentication](https://bcs-mcp-atlassian.soomiles.com/docs/authentication) | API tokens, PAT, OAuth 2.0 |
| [Configuration](https://bcs-mcp-atlassian.soomiles.com/docs/configuration) | IDE setup, environment variables |
| [HTTP Transport](https://bcs-mcp-atlassian.soomiles.com/docs/http-transport) | SSE, streamable-http, multi-user |
| [Tools Reference](https://bcs-mcp-atlassian.soomiles.com/docs/tools-reference) | All Jira & Confluence tools |
| [Troubleshooting](https://bcs-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 total** — See [Tools Reference](https://bcs-mcp-atlassian.soomiles.com/docs/tools-reference) for the complete list.

## Security

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.

## License

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