# Atlassian MCP Server
[](https://badge.fury.io/py/atlassian-mcp-server)
[](https://pypi.org/project/atlassian-mcp-server/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/rorymcmahon/atlassian-mcp-server/actions/workflows/pylint.yml)
[](https://github.com/rorymcmahon/atlassian-mcp-server/actions/workflows/dependency-security.yml)
MCP server for Atlassian Cloud (Confluence & Jira) with seamless OAuth 2.0 authentication. This server enables AI agents to help users document work in Confluence, manage Jira issues, and understand project context.
## Features
- **Seamless OAuth 2.0 Flow**: Automatic browser-based authentication with PKCE security
- **Modular Architecture**: Specialized client classes for Jira, Confluence, and Service Desk operations
- **Selective Module Loading**: Configure which modules to load using environment variables
- **Jira Integration**: Search, create, and update issues; add comments; manage work
- **Confluence Integration**: Search and read content for context understanding
- **Service Management**: Access support tickets and requests
- **Automatic Token Management**: Handles token refresh automatically
- **Minimal Permissions**: Follows least privilege principle with only required scopes
## Architecture
The server uses a modular architecture with specialized client classes:
- **BaseAtlassianClient**: Core OAuth 2.0 authentication and HTTP request handling
- **JiraClient**: Jira-specific operations (issues, projects, comments)
- **ConfluenceClient**: Confluence-specific operations (pages, spaces, search)
- **ServiceDeskClient**: Service Management operations (requests, approvals, Assets CMDB)
Each module can be independently enabled/disabled for optimal performance and security.
## Use Cases
This MCP server is designed to help AI agents assist users with:
- **Work Documentation**: Help document work progress and decisions in Confluence
- **Issue Management**: Create, update, and track Jira issues based on conversations
- **Context Understanding**: Read Confluence pages to understand project background
- **Time & Activity Logging**: Track work activities and time spent on tasks
- **Service Requests**: Access service management tickets for support context
- **Project Coordination**: Search across Jira and Confluence for project information
## OAuth App Setup
### 1. Create OAuth App
1. Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
2. Click **Create** → **OAuth 2.0 integration**
3. Enter your app name and accept the terms
4. Set **Callback URL** to: `http://localhost:8080/callback`
### 2. Configure Required Scopes
**IMPORTANT**: You must add these exact scopes to your OAuth app before the MCP server can function properly.
#### Jira API Scopes
Navigate to **Permissions** → **Jira API** and add:
- `read:jira-work` - Read issues, projects, and search
- `read:jira-user` - Read user information
- `write:jira-work` - Create and update issues
#### Confluence API Scopes
Navigate to **Permissions** → **Confluence API** and add:
- `read:page:confluence` - Read page content (granular scope for v2 API)
- `read:space:confluence` - Read space information (granular scope for v2 API)
- `write:page:confluence` - Create and update pages (granular scope for v2 API)
#### Service Management API Scopes
Navigate to **Permissions** → **Jira Service Management API** and add:
- `read:servicedesk-request` - Read service management requests
- `write:servicedesk-request` - Create and update service management requests
- `manage:servicedesk-customer` - Manage service desk customers and participants
- `read:knowledgebase:jira-service-management` - Search knowledge base articles
#### User Identity API Scopes
Navigate to **Permissions** → **User identity API** and add:
- `read:me` - User profile information
#### Core Scopes
These are typically available by default:
- `offline_access` - Token refresh capability
### 3. Install App to Your Atlassian Site
After configuring scopes, you need to install the app to your Atlassian site:
1. In your OAuth app, go to **Authorization** tab
2. Use the **Authorization URL generator** to create an installation URL:
- Select your configured scopes
- Choose your Atlassian site from the dropdown
- Click **Generate URL**
3. **Visit the generated URL** in your browser to install the app to your site
4. **Grant permissions** when prompted by Atlassian
**Note**: This step is required before the MCP server can access your Atlassian data. The app must be installed and authorized for your specific site.
### 4. Get Your Credentials
After installing the app:
1. Go to **Settings** tab in your OAuth app
2. Copy your **Client ID** and **Client Secret**
3. Set the environment variables (see Configuration section below)
### 5. Scope Configuration Summary
**Minimal Required (12 scopes):**
```
read:jira-work
read:jira-user
write:jira-work
read:page:confluence
read:space:confluence
write:page:confluence
read:servicedesk-request
write:servicedesk-request
manage:servicedesk-customer
read:knowledgebase:jira-service-management
read:me
offline_access
```
**Optional (add only if needed):**
```
write:servicedesk-request # Only if creating service tickets
manage:* scopes # Only for administrative operations
```
### 6. Troubleshooting Scopes
If you get scope-related errors:
- **"scope does not match"**: The scope isn't added to your OAuth app in Developer Console
- **"Current user not permitted"**: User lacks product-level permissions (contact your Atlassian admin)
- **"Unauthorized"**: Check that all required scopes are properly configured
**Note**: After adding new scopes to your OAuth app, you must re-authenticate using the `authenticate_atlassian` tool to get fresh tokens with the new permissions.
## Installation
### Prerequisites
- Python 3.8 or higher
- pip3 package manager
- Access to an Atlassian Cloud site
- OAuth app configured (see OAuth App Setup above)
### Install from PyPI (Recommended)
```bash
pip3 install atlassian-mcp-server
```
### Install from GitHub Repository
```bash
# Install directly from GitHub repository
pip3 install git+https://github.com/rorymcmahon/atlassian-mcp-server.git
```
### Install from Source
```bash
# Clone the repository
git clone https://github.com/rorymcmahon/atlassian-mcp-server.git
cd atlassian-mcp-server
# Install in development mode
pip3 install -e .
```
### Verify Installation
```bash
# Check that the command is available
atlassian-mcp-server --help
# Or check the Python module
python -m atlassian_mcp_server --help
```
## Configuration
Set the following environment variables:
```bash
export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_CLIENT_ID="your-oauth-client-id"
export ATLASSIAN_CLIENT_SECRET="your-oauth-client-secret"
```
### Optional Configuration
**Module Selection**: Control which modules are loaded (default: all modules enabled):
```bash
export ATLASSIAN_MODULES="jira,confluence,service_desk" # Enable specific modules
export ATLASSIAN_MODULES="jira,confluence" # Enable only Jira and Confluence
export ATLASSIAN_MODULES="jira" # Enable only Jira
```
Available modules:
- `jira` - Jira issue management and project operations
- `confluence` - Confluence page and space operations
- `service_desk` - Service Management and Assets CMDB operations
**Note**: Disabling unused modules reduces memory usage and improves startup time.
## Usage
```bash
# Start the MCP server
python -m atlassian_mcp_server
# Or run directly
python src/atlassian_mcp_server/server.py
```
## MCP Client Configuration
**Note**: All configuration examples below show the required environment variables. You can optionally add `"ATLASSIAN_MODULES": "jira,confluence,service_desk"` to any `env` section to control which modules are loaded.
### Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"atlassian": {
"command": "atlassian-mcp-server",
"env": {
"ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
"ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
"ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
}
}
}
}
```
### Amazon Q Developer CLI
Create an agent configuration file:
**File**: `~/.aws/amazonq/cli-agents/atlassian.json`
```json
{
"$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
"name": "atlassian",
"description": "Atlassian Jira and Confluence integration agent",
"prompt": "You are an AI assistant with access to Atlassian Jira and Confluence. Help users manage issues, search content, and document their work.",
"mcpServers": {
"atlassian-mcp-server": {
"command": "atlassian-mcp-server",
"args": [],
"env": {
"ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
"ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
"ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
},
"autoApprove": ["*"],
"disabled": false,
"timeout": 60000,
"initTimeout": 120000
}
},
"tools": [
"@atlassian-mcp-server/*"
],
"allowedTools": [
"@atlassian-mcp-server/*"
]
}
```
Then use: `q chat --agent atlassian`
### VS Code with Continue
Add to your Continue configuration:
**File**: `~/.continue/config.json`
```json
{
"models": [...],
"mcpServers": {
"atlassian": {
"command": "atlassian-mcp-server",
"env": {
"ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
"ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
"ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
}
}
}
}
```
### VS Code with GitHub Copilot Chat
For GitHub Copilot Chat with MCP support, add to workspace settings:
**File**: `.vscode/settings.json`
```json
{
"github.copilot.chat.mcp.servers": {
"atlassian": {
"command": "atlassian-mcp-server",
"env": {
"ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
"ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
"ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
}
}
}
}
```
### Cline (VS Code Extension)
Add to Cline's MCP configuration:
**File**: `~/.cline/mcp_servers.json`
```json
{
"atlassian": {
"command": "atlassian-mcp-server",
"env": {
"ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
"ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
"ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
}
}
}
```
### Environment Variables Setup
For security, set environment variables instead of hardcoding in config files:
```bash
# Add to your shell profile (.bashrc, .zshrc, etc.)
export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_CLIENT_ID="your-oauth-client-id"
export ATLASSIAN_CLIENT_SECRET="your-oauth-client-secret"
```
Then use in configurations:
```json
{
"env": {
"ATLASSIAN_SITE_URL": "${ATLASSIAN_SITE_URL}",
"ATLASSIAN_CLIENT_ID": "${ATLASSIAN_CLIENT_ID}",
"ATLASSIAN_CLIENT_SECRET": "${ATLASSIAN_CLIENT_SECRET}"
}
}
```
## Authentication Flow
1. Start the MCP server
2. Use the `authenticate_atlassian` tool to begin OAuth flow
3. Browser opens automatically to Atlassian login
4. After authorization, authentication completes automatically
5. Credentials are saved locally for future use
## Available Tools
### Authentication
- `authenticate_atlassian()` - Start seamless OAuth authentication flow
### Jira Operations
- `jira_search(jql, max_results=50)` - Search issues with JQL
- `jira_get_issue(issue_key)` - Get specific issue details
- `jira_create_issue(project_key, summary, description, issue_type="Task")` - Create new issue
- `jira_update_issue(issue_key, summary=None, description=None)` - Update existing issue
- `jira_add_comment(issue_key, comment)` - Add comment to issue
### Confluence Operations
#### Core Content Management
- `confluence_search(query, limit=10)` - Search Confluence content
- `confluence_get_page(page_id)` - Get specific page content
- `confluence_create_page(space_key, title, content, parent_id=None)` - Create new Confluence page
- `confluence_update_page(page_id, title, content, version)` - Update existing Confluence page
#### Space Management
- `confluence_list_spaces(limit=25, space_type=None, status="current")` - List available spaces
- `confluence_get_space(space_id, include_icon=False)` - Get detailed space information
- `confluence_get_space_pages(space_id, limit=25, status="current")` - Get pages in a space
#### Enhanced Search & Discovery
- `confluence_search_content(query, limit=25, space_id=None)` - Advanced content search
- `confluence_get_page_children(page_id, limit=25)` - Get child pages
#### Comments & Collaboration
- `confluence_get_page_comments(page_id, limit=25)` - Get page comments
- `confluence_add_comment(page_id, comment, parent_comment_id=None)` - Add comment to page
- `confluence_get_comment(comment_id)` - Get specific comment details
#### Labels & Organization
- `confluence_get_page_labels(page_id, limit=25)` - Get labels for a page
- `confluence_search_by_label(label_id, limit=25)` - Find pages with specific label
- `confluence_list_labels(limit=25, prefix=None)` - List all available labels
#### Attachments
- `confluence_get_page_attachments(page_id, limit=25)` - Get page attachments
- `confluence_get_attachment(attachment_id)` - Get attachment details
#### Version History
- `confluence_get_page_versions(page_id, limit=25)` - Get page version history
- `confluence_get_page_version(page_id, version_number)` - Get specific page version
### Service Management Operations
#### Discovery Tools (Essential for AI Agents)
- `servicedesk_check_availability()` - Check if Jira Service Management is configured
- `servicedesk_list_service_desks(limit=50)` - List available service desks for creating requests
- `servicedesk_get_service_desk(service_desk_id)` - Get detailed service desk information
- `servicedesk_list_request_types(service_desk_id=None, limit=50)` - List available request types
- `servicedesk_get_request_type(service_desk_id, request_type_id)` - Get detailed request type information
- `servicedesk_get_request_type_fields(service_desk_id, request_type_id)` - Get required/optional fields for request type
#### Request Management
- `servicedesk_get_requests(service_desk_id=None, limit=50)` - Get service desk requests
- `servicedesk_get_request(issue_key)` - Get specific service desk request details
- `servicedesk_create_request(service_desk_id, request_type_id, summary, description)` - Create new service request
- `servicedesk_add_comment(issue_key, comment, public=True)` - Add comment to service request
- `servicedesk_get_request_comments(issue_key, limit=50)` - Get comments for a service request
- `servicedesk_get_request_status(issue_key)` - Get service request status
- `servicedesk_get_request_transitions(issue_key)` - Get available status transitions for request
- `servicedesk_transition_request(issue_key, transition_id, comment=None)` - Transition request to new status
#### Approval & Participant Management
- `servicedesk_get_approvals(issue_key)` - Get approval information for request
- `servicedesk_approve_request(issue_key, approval_id, decision)` - Approve or decline request approval
- `servicedesk_get_participants(issue_key)` - Get participants for request
- `servicedesk_add_participants(issue_key, usernames)` - Add participants to request (with confirmation prompts)
- `servicedesk_manage_notifications(issue_key, subscribe)` - Subscribe/unsubscribe from request notifications
## Troubleshooting
### Authentication Issues
- Ensure redirect URI matches exactly: `http://localhost:8080/callback`
- Check that all required scopes are configured in Atlassian Developer Console
- Verify environment variables are set correctly
### Permission Issues
- Ensure your user has appropriate Jira and Confluence access
- Check that OAuth app has all required scopes enabled
- Verify user is in correct groups (e.g., confluence-users)
### API Errors
- Check that your Atlassian site URL is correct
- Ensure you have proper permissions for the resources you're accessing
- Run the test scripts to verify functionality
## Scope Requirements
This MCP server uses **minimal required scopes** following the principle of least privilege:
### Essential Scopes (16 total)
- **Jira**: `read:jira-work`, `read:jira-user`, `write:jira-work`
- **Confluence**: `read:page:confluence`, `read:space:confluence`, `write:page:confluence`, `read:comment:confluence`, `write:comment:confluence`, `read:label:confluence`, `read:attachment:confluence`
- **Service Management**: `read:servicedesk-request`, `write:servicedesk-request`, `manage:servicedesk-customer`, `read:knowledgebase:jira-service-management`
- **Core**: `read:me`, `offline_access`
### Optional Scopes (add only if needed)
- `manage:*` scopes - Only for administrative operations
## Important: Granular Scopes for v2 API
This MCP server uses **granular scopes** for Confluence operations to ensure compatibility with Confluence v2 API endpoints. The v2 API provides better performance and future-proofing compared to the deprecated v1 REST API.
**Granular vs Classic Scopes:**
- **Granular** (recommended): `read:page:confluence`, `write:page:confluence` - Works with v2 API
- **Classic** (deprecated): `read:confluence-content.all`, `write:confluence-content` - Only works with v1 API
If you previously configured classic scopes, you'll need to update your OAuth app to use granular scopes and re-authenticate to get fresh tokens.
## Supply Chain Security
This project implements comprehensive supply chain security measures:
### Dependency Management
- **Pinned Versions**: All dependencies use exact version pins to prevent unexpected updates
- **Security Scanning**: Automated vulnerability scanning with Safety and pip-audit
- **Dependency Tracking**: Complete dependency documentation in `docs/DEPENDENCIES.md`
- **Regular Updates**: Weekly automated security checks via GitHub Actions
### Security Tools
```bash
# Generate dependency report
python3 scripts/generate_dependency_report.py
# Check for vulnerabilities
pip3 install safety pip-audit
safety check
pip-audit
# Update dependencies safely
python3 scripts/update_dependencies.py
```
### Files
- `requirements.txt` - Pinned production dependencies
- `docs/DEPENDENCIES.md` - Human-readable dependency report
- `docs/dependency-report.json` - Machine-readable dependency data
- `SECURITY.md` - Security policy and vulnerability response
- `.github/workflows/dependency-security.yml` - Automated security checks
## Development
The server is built using:
- **FastMCP**: Modern MCP server framework
- **httpx**: Async HTTP client
- **Pydantic**: Data validation and settings management
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "atlassian-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, atlassian, jira, confluence, oauth, ai, assistant",
"author": null,
"author_email": "Rory McMahon <rory.mcmahon@vocus.com.au>",
"download_url": "https://files.pythonhosted.org/packages/64/72/e7af5e5b63a113679856d4475ee9d91882e557a01319d92ad9138f02018c/atlassian_mcp_server-0.4.2.tar.gz",
"platform": null,
"description": "# Atlassian MCP Server\n\n[](https://badge.fury.io/py/atlassian-mcp-server)\n[](https://pypi.org/project/atlassian-mcp-server/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/rorymcmahon/atlassian-mcp-server/actions/workflows/pylint.yml)\n[](https://github.com/rorymcmahon/atlassian-mcp-server/actions/workflows/dependency-security.yml)\n\nMCP server for Atlassian Cloud (Confluence & Jira) with seamless OAuth 2.0 authentication. This server enables AI agents to help users document work in Confluence, manage Jira issues, and understand project context.\n\n## Features\n\n- **Seamless OAuth 2.0 Flow**: Automatic browser-based authentication with PKCE security\n- **Modular Architecture**: Specialized client classes for Jira, Confluence, and Service Desk operations\n- **Selective Module Loading**: Configure which modules to load using environment variables\n- **Jira Integration**: Search, create, and update issues; add comments; manage work\n- **Confluence Integration**: Search and read content for context understanding\n- **Service Management**: Access support tickets and requests\n- **Automatic Token Management**: Handles token refresh automatically\n- **Minimal Permissions**: Follows least privilege principle with only required scopes\n\n## Architecture\n\nThe server uses a modular architecture with specialized client classes:\n\n- **BaseAtlassianClient**: Core OAuth 2.0 authentication and HTTP request handling\n- **JiraClient**: Jira-specific operations (issues, projects, comments)\n- **ConfluenceClient**: Confluence-specific operations (pages, spaces, search)\n- **ServiceDeskClient**: Service Management operations (requests, approvals, Assets CMDB)\n\nEach module can be independently enabled/disabled for optimal performance and security.\n\n## Use Cases\n\nThis MCP server is designed to help AI agents assist users with:\n\n- **Work Documentation**: Help document work progress and decisions in Confluence\n- **Issue Management**: Create, update, and track Jira issues based on conversations\n- **Context Understanding**: Read Confluence pages to understand project background\n- **Time & Activity Logging**: Track work activities and time spent on tasks\n- **Service Requests**: Access service management tickets for support context\n- **Project Coordination**: Search across Jira and Confluence for project information\n\n## OAuth App Setup\n\n### 1. Create OAuth App\n\n1. Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)\n2. Click **Create** \u2192 **OAuth 2.0 integration**\n3. Enter your app name and accept the terms\n4. Set **Callback URL** to: `http://localhost:8080/callback`\n\n### 2. Configure Required Scopes\n\n**IMPORTANT**: You must add these exact scopes to your OAuth app before the MCP server can function properly.\n\n#### Jira API Scopes\nNavigate to **Permissions** \u2192 **Jira API** and add:\n- `read:jira-work` - Read issues, projects, and search\n- `read:jira-user` - Read user information \n- `write:jira-work` - Create and update issues\n\n#### Confluence API Scopes\nNavigate to **Permissions** \u2192 **Confluence API** and add:\n- `read:page:confluence` - Read page content (granular scope for v2 API)\n- `read:space:confluence` - Read space information (granular scope for v2 API) \n- `write:page:confluence` - Create and update pages (granular scope for v2 API)\n\n#### Service Management API Scopes\nNavigate to **Permissions** \u2192 **Jira Service Management API** and add:\n- `read:servicedesk-request` - Read service management requests\n- `write:servicedesk-request` - Create and update service management requests \n- `manage:servicedesk-customer` - Manage service desk customers and participants\n- `read:knowledgebase:jira-service-management` - Search knowledge base articles\n\n#### User Identity API Scopes\nNavigate to **Permissions** \u2192 **User identity API** and add:\n- `read:me` - User profile information\n\n#### Core Scopes\nThese are typically available by default:\n- `offline_access` - Token refresh capability\n\n### 3. Install App to Your Atlassian Site\n\nAfter configuring scopes, you need to install the app to your Atlassian site:\n\n1. In your OAuth app, go to **Authorization** tab\n2. Use the **Authorization URL generator** to create an installation URL:\n - Select your configured scopes\n - Choose your Atlassian site from the dropdown\n - Click **Generate URL**\n3. **Visit the generated URL** in your browser to install the app to your site\n4. **Grant permissions** when prompted by Atlassian\n\n**Note**: This step is required before the MCP server can access your Atlassian data. The app must be installed and authorized for your specific site.\n\n### 4. Get Your Credentials\n\nAfter installing the app:\n1. Go to **Settings** tab in your OAuth app\n2. Copy your **Client ID** and **Client Secret**\n3. Set the environment variables (see Configuration section below)\n\n### 5. Scope Configuration Summary\n\n**Minimal Required (12 scopes):**\n```\nread:jira-work\nread:jira-user \nwrite:jira-work\nread:page:confluence\nread:space:confluence\nwrite:page:confluence\nread:servicedesk-request\nwrite:servicedesk-request\nmanage:servicedesk-customer\nread:knowledgebase:jira-service-management\nread:me\noffline_access\n```\n\n**Optional (add only if needed):**\n```\nwrite:servicedesk-request # Only if creating service tickets\nmanage:* scopes # Only for administrative operations\n```\n\n### 6. Troubleshooting Scopes\n\nIf you get scope-related errors:\n- **\"scope does not match\"**: The scope isn't added to your OAuth app in Developer Console\n- **\"Current user not permitted\"**: User lacks product-level permissions (contact your Atlassian admin)\n- **\"Unauthorized\"**: Check that all required scopes are properly configured\n\n**Note**: After adding new scopes to your OAuth app, you must re-authenticate using the `authenticate_atlassian` tool to get fresh tokens with the new permissions.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- pip3 package manager\n- Access to an Atlassian Cloud site\n- OAuth app configured (see OAuth App Setup above)\n\n### Install from PyPI (Recommended)\n\n```bash\npip3 install atlassian-mcp-server\n```\n\n### Install from GitHub Repository\n\n```bash\n# Install directly from GitHub repository\npip3 install git+https://github.com/rorymcmahon/atlassian-mcp-server.git\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/rorymcmahon/atlassian-mcp-server.git\ncd atlassian-mcp-server\n\n# Install in development mode\npip3 install -e .\n```\n\n### Verify Installation\n\n```bash\n# Check that the command is available\natlassian-mcp-server --help\n\n# Or check the Python module\npython -m atlassian_mcp_server --help\n```\n\n## Configuration\n\nSet the following environment variables:\n\n```bash\nexport ATLASSIAN_SITE_URL=\"https://your-domain.atlassian.net\"\nexport ATLASSIAN_CLIENT_ID=\"your-oauth-client-id\"\nexport ATLASSIAN_CLIENT_SECRET=\"your-oauth-client-secret\"\n```\n\n### Optional Configuration\n\n**Module Selection**: Control which modules are loaded (default: all modules enabled):\n```bash\nexport ATLASSIAN_MODULES=\"jira,confluence,service_desk\" # Enable specific modules\nexport ATLASSIAN_MODULES=\"jira,confluence\" # Enable only Jira and Confluence\nexport ATLASSIAN_MODULES=\"jira\" # Enable only Jira\n```\n\nAvailable modules:\n- `jira` - Jira issue management and project operations\n- `confluence` - Confluence page and space operations \n- `service_desk` - Service Management and Assets CMDB operations\n\n**Note**: Disabling unused modules reduces memory usage and improves startup time.\n\n## Usage\n\n```bash\n# Start the MCP server\npython -m atlassian_mcp_server\n\n# Or run directly\npython src/atlassian_mcp_server/server.py\n```\n\n## MCP Client Configuration\n\n**Note**: All configuration examples below show the required environment variables. You can optionally add `\"ATLASSIAN_MODULES\": \"jira,confluence,service_desk\"` to any `env` section to control which modules are loaded.\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"atlassian\": {\n \"command\": \"atlassian-mcp-server\",\n \"env\": {\n \"ATLASSIAN_SITE_URL\": \"https://your-domain.atlassian.net\",\n \"ATLASSIAN_CLIENT_ID\": \"your-oauth-client-id\",\n \"ATLASSIAN_CLIENT_SECRET\": \"your-oauth-client-secret\"\n }\n }\n }\n}\n```\n\n### Amazon Q Developer CLI\n\nCreate an agent configuration file:\n\n**File**: `~/.aws/amazonq/cli-agents/atlassian.json`\n\n```json\n{\n \"$schema\": \"https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json\",\n \"name\": \"atlassian\",\n \"description\": \"Atlassian Jira and Confluence integration agent\",\n \"prompt\": \"You are an AI assistant with access to Atlassian Jira and Confluence. Help users manage issues, search content, and document their work.\",\n \"mcpServers\": {\n \"atlassian-mcp-server\": {\n \"command\": \"atlassian-mcp-server\",\n \"args\": [],\n \"env\": {\n \"ATLASSIAN_SITE_URL\": \"https://your-domain.atlassian.net\",\n \"ATLASSIAN_CLIENT_ID\": \"your-oauth-client-id\",\n \"ATLASSIAN_CLIENT_SECRET\": \"your-oauth-client-secret\"\n },\n \"autoApprove\": [\"*\"],\n \"disabled\": false,\n \"timeout\": 60000,\n \"initTimeout\": 120000\n }\n },\n \"tools\": [\n \"@atlassian-mcp-server/*\"\n ],\n \"allowedTools\": [\n \"@atlassian-mcp-server/*\"\n ]\n}\n```\n\nThen use: `q chat --agent atlassian`\n\n### VS Code with Continue\n\nAdd to your Continue configuration:\n\n**File**: `~/.continue/config.json`\n\n```json\n{\n \"models\": [...],\n \"mcpServers\": {\n \"atlassian\": {\n \"command\": \"atlassian-mcp-server\",\n \"env\": {\n \"ATLASSIAN_SITE_URL\": \"https://your-domain.atlassian.net\",\n \"ATLASSIAN_CLIENT_ID\": \"your-oauth-client-id\",\n \"ATLASSIAN_CLIENT_SECRET\": \"your-oauth-client-secret\"\n }\n }\n }\n}\n```\n\n### VS Code with GitHub Copilot Chat\n\nFor GitHub Copilot Chat with MCP support, add to workspace settings:\n\n**File**: `.vscode/settings.json`\n\n```json\n{\n \"github.copilot.chat.mcp.servers\": {\n \"atlassian\": {\n \"command\": \"atlassian-mcp-server\",\n \"env\": {\n \"ATLASSIAN_SITE_URL\": \"https://your-domain.atlassian.net\",\n \"ATLASSIAN_CLIENT_ID\": \"your-oauth-client-id\",\n \"ATLASSIAN_CLIENT_SECRET\": \"your-oauth-client-secret\"\n }\n }\n }\n}\n```\n\n### Cline (VS Code Extension)\n\nAdd to Cline's MCP configuration:\n\n**File**: `~/.cline/mcp_servers.json`\n\n```json\n{\n \"atlassian\": {\n \"command\": \"atlassian-mcp-server\",\n \"env\": {\n \"ATLASSIAN_SITE_URL\": \"https://your-domain.atlassian.net\",\n \"ATLASSIAN_CLIENT_ID\": \"your-oauth-client-id\",\n \"ATLASSIAN_CLIENT_SECRET\": \"your-oauth-client-secret\"\n }\n }\n}\n```\n\n### Environment Variables Setup\n\nFor security, set environment variables instead of hardcoding in config files:\n\n```bash\n# Add to your shell profile (.bashrc, .zshrc, etc.)\nexport ATLASSIAN_SITE_URL=\"https://your-domain.atlassian.net\"\nexport ATLASSIAN_CLIENT_ID=\"your-oauth-client-id\"\nexport ATLASSIAN_CLIENT_SECRET=\"your-oauth-client-secret\"\n```\n\nThen use in configurations:\n```json\n{\n \"env\": {\n \"ATLASSIAN_SITE_URL\": \"${ATLASSIAN_SITE_URL}\",\n \"ATLASSIAN_CLIENT_ID\": \"${ATLASSIAN_CLIENT_ID}\",\n \"ATLASSIAN_CLIENT_SECRET\": \"${ATLASSIAN_CLIENT_SECRET}\"\n }\n}\n```\n\n## Authentication Flow\n\n1. Start the MCP server\n2. Use the `authenticate_atlassian` tool to begin OAuth flow\n3. Browser opens automatically to Atlassian login\n4. After authorization, authentication completes automatically\n5. Credentials are saved locally for future use\n\n## Available Tools\n\n### Authentication\n- `authenticate_atlassian()` - Start seamless OAuth authentication flow\n\n### Jira Operations\n- `jira_search(jql, max_results=50)` - Search issues with JQL\n- `jira_get_issue(issue_key)` - Get specific issue details\n- `jira_create_issue(project_key, summary, description, issue_type=\"Task\")` - Create new issue\n- `jira_update_issue(issue_key, summary=None, description=None)` - Update existing issue\n- `jira_add_comment(issue_key, comment)` - Add comment to issue\n\n### Confluence Operations\n\n#### Core Content Management\n- `confluence_search(query, limit=10)` - Search Confluence content\n- `confluence_get_page(page_id)` - Get specific page content\n- `confluence_create_page(space_key, title, content, parent_id=None)` - Create new Confluence page\n- `confluence_update_page(page_id, title, content, version)` - Update existing Confluence page\n\n#### Space Management\n- `confluence_list_spaces(limit=25, space_type=None, status=\"current\")` - List available spaces\n- `confluence_get_space(space_id, include_icon=False)` - Get detailed space information\n- `confluence_get_space_pages(space_id, limit=25, status=\"current\")` - Get pages in a space\n\n#### Enhanced Search & Discovery\n- `confluence_search_content(query, limit=25, space_id=None)` - Advanced content search\n- `confluence_get_page_children(page_id, limit=25)` - Get child pages\n\n#### Comments & Collaboration\n- `confluence_get_page_comments(page_id, limit=25)` - Get page comments\n- `confluence_add_comment(page_id, comment, parent_comment_id=None)` - Add comment to page\n- `confluence_get_comment(comment_id)` - Get specific comment details\n\n#### Labels & Organization\n- `confluence_get_page_labels(page_id, limit=25)` - Get labels for a page\n- `confluence_search_by_label(label_id, limit=25)` - Find pages with specific label\n- `confluence_list_labels(limit=25, prefix=None)` - List all available labels\n\n#### Attachments\n- `confluence_get_page_attachments(page_id, limit=25)` - Get page attachments\n- `confluence_get_attachment(attachment_id)` - Get attachment details\n\n#### Version History\n- `confluence_get_page_versions(page_id, limit=25)` - Get page version history\n- `confluence_get_page_version(page_id, version_number)` - Get specific page version\n\n### Service Management Operations\n\n#### Discovery Tools (Essential for AI Agents)\n- `servicedesk_check_availability()` - Check if Jira Service Management is configured\n- `servicedesk_list_service_desks(limit=50)` - List available service desks for creating requests\n- `servicedesk_get_service_desk(service_desk_id)` - Get detailed service desk information\n- `servicedesk_list_request_types(service_desk_id=None, limit=50)` - List available request types\n- `servicedesk_get_request_type(service_desk_id, request_type_id)` - Get detailed request type information\n- `servicedesk_get_request_type_fields(service_desk_id, request_type_id)` - Get required/optional fields for request type\n\n#### Request Management\n- `servicedesk_get_requests(service_desk_id=None, limit=50)` - Get service desk requests\n- `servicedesk_get_request(issue_key)` - Get specific service desk request details\n- `servicedesk_create_request(service_desk_id, request_type_id, summary, description)` - Create new service request\n- `servicedesk_add_comment(issue_key, comment, public=True)` - Add comment to service request\n- `servicedesk_get_request_comments(issue_key, limit=50)` - Get comments for a service request\n- `servicedesk_get_request_status(issue_key)` - Get service request status\n- `servicedesk_get_request_transitions(issue_key)` - Get available status transitions for request\n- `servicedesk_transition_request(issue_key, transition_id, comment=None)` - Transition request to new status\n\n#### Approval & Participant Management\n- `servicedesk_get_approvals(issue_key)` - Get approval information for request\n- `servicedesk_approve_request(issue_key, approval_id, decision)` - Approve or decline request approval\n- `servicedesk_get_participants(issue_key)` - Get participants for request\n- `servicedesk_add_participants(issue_key, usernames)` - Add participants to request (with confirmation prompts)\n- `servicedesk_manage_notifications(issue_key, subscribe)` - Subscribe/unsubscribe from request notifications\n\n## Troubleshooting\n\n### Authentication Issues\n- Ensure redirect URI matches exactly: `http://localhost:8080/callback`\n- Check that all required scopes are configured in Atlassian Developer Console\n- Verify environment variables are set correctly\n\n### Permission Issues\n- Ensure your user has appropriate Jira and Confluence access\n- Check that OAuth app has all required scopes enabled\n- Verify user is in correct groups (e.g., confluence-users)\n\n### API Errors\n- Check that your Atlassian site URL is correct\n- Ensure you have proper permissions for the resources you're accessing\n- Run the test scripts to verify functionality\n\n## Scope Requirements\n\nThis MCP server uses **minimal required scopes** following the principle of least privilege:\n\n### Essential Scopes (16 total)\n- **Jira**: `read:jira-work`, `read:jira-user`, `write:jira-work`\n- **Confluence**: `read:page:confluence`, `read:space:confluence`, `write:page:confluence`, `read:comment:confluence`, `write:comment:confluence`, `read:label:confluence`, `read:attachment:confluence`\n- **Service Management**: `read:servicedesk-request`, `write:servicedesk-request`, `manage:servicedesk-customer`, `read:knowledgebase:jira-service-management`\n- **Core**: `read:me`, `offline_access`\n\n### Optional Scopes (add only if needed)\n- `manage:*` scopes - Only for administrative operations\n\n## Important: Granular Scopes for v2 API\n\nThis MCP server uses **granular scopes** for Confluence operations to ensure compatibility with Confluence v2 API endpoints. The v2 API provides better performance and future-proofing compared to the deprecated v1 REST API.\n\n**Granular vs Classic Scopes:**\n- **Granular** (recommended): `read:page:confluence`, `write:page:confluence` - Works with v2 API\n- **Classic** (deprecated): `read:confluence-content.all`, `write:confluence-content` - Only works with v1 API\n\nIf you previously configured classic scopes, you'll need to update your OAuth app to use granular scopes and re-authenticate to get fresh tokens.\n\n## Supply Chain Security\n\nThis project implements comprehensive supply chain security measures:\n\n### Dependency Management\n- **Pinned Versions**: All dependencies use exact version pins to prevent unexpected updates\n- **Security Scanning**: Automated vulnerability scanning with Safety and pip-audit\n- **Dependency Tracking**: Complete dependency documentation in `docs/DEPENDENCIES.md`\n- **Regular Updates**: Weekly automated security checks via GitHub Actions\n\n### Security Tools\n```bash\n# Generate dependency report\npython3 scripts/generate_dependency_report.py\n\n# Check for vulnerabilities\npip3 install safety pip-audit\nsafety check\npip-audit\n\n# Update dependencies safely\npython3 scripts/update_dependencies.py\n```\n\n### Files\n- `requirements.txt` - Pinned production dependencies\n- `docs/DEPENDENCIES.md` - Human-readable dependency report\n- `docs/dependency-report.json` - Machine-readable dependency data\n- `SECURITY.md` - Security policy and vulnerability response\n- `.github/workflows/dependency-security.yml` - Automated security checks\n\n## Development\n\nThe server is built using:\n- **FastMCP**: Modern MCP server framework\n- **httpx**: Async HTTP client\n- **Pydantic**: Data validation and settings management\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Atlassian Cloud (Confluence & Jira) with seamless OAuth 2.0 authentication",
"version": "0.4.2",
"project_urls": {
"Documentation": "https://github.com/InfraMCP/atlassian-mcp-server#readme",
"Homepage": "https://github.com/InfraMCP/atlassian-mcp-server",
"Issues": "https://github.com/InfraMCP/atlassian-mcp-server/issues",
"Repository": "https://github.com/InfraMCP/atlassian-mcp-server"
},
"split_keywords": [
"mcp",
" atlassian",
" jira",
" confluence",
" oauth",
" ai",
" assistant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "beef9d1c8d90c8737484db7ae224de7d0873a34a15952694c9398b9e6b20982f",
"md5": "e9ca45ad3e883fb54da34e4c2e90e909",
"sha256": "a4602bcd56fc36cddce32aad23673de29cd744086807279fff5828a378e957e5"
},
"downloads": -1,
"filename": "atlassian_mcp_server-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9ca45ad3e883fb54da34e4c2e90e909",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27571,
"upload_time": "2025-10-06T06:51:21",
"upload_time_iso_8601": "2025-10-06T06:51:21.127463Z",
"url": "https://files.pythonhosted.org/packages/be/ef/9d1c8d90c8737484db7ae224de7d0873a34a15952694c9398b9e6b20982f/atlassian_mcp_server-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6472e7af5e5b63a113679856d4475ee9d91882e557a01319d92ad9138f02018c",
"md5": "344661590319cbdc2187d06027baa4b7",
"sha256": "dadbae1431e3500f573507f98bf920aafb39cf51a2536b21a4a56946ded86063"
},
"downloads": -1,
"filename": "atlassian_mcp_server-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "344661590319cbdc2187d06027baa4b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 32470,
"upload_time": "2025-10-06T06:51:22",
"upload_time_iso_8601": "2025-10-06T06:51:22.377737Z",
"url": "https://files.pythonhosted.org/packages/64/72/e7af5e5b63a113679856d4475ee9d91882e557a01319d92ad9138f02018c/atlassian_mcp_server-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 06:51:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "InfraMCP",
"github_project": "atlassian-mcp-server#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
"==",
"1.14.1"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.11.9"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
"==",
"2.10.1"
]
]
}
],
"lcname": "atlassian-mcp-server"
}
JSON
