Atlassian-mcp-server

MCP server for Atlassian Cloud (Confluence & Jira) with seamless OAuth 2.0 authentication.

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.

- 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

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.

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
- Go toAtlassian Developer Console
- ClickCreate→OAuth 2.0 integration
- Enter your app name and accept the terms
- SetCallback URLto:http://localhost:8080/callback

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

write:servicedesk-request # Only if creating service tickets manage: scopes # Only for administrative operations

# Install directly from GitHub repository pip3 install git+https://github.com/rorymcmahon/atlassian-mcp-server.git

# Clone the repository git clone https://github.com/rorymcmahon/atlassian-mcp-server.git cd atlassian-mcp-server # Install in development mode pip3 install -e .

# Check that the command is available atlassian-mcp-server --help # Or check the Python module python -m atlassian_mcp_server --help

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"

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

# Start the MCP server python -m atlassian_mcp_server # Or run directly python src/atlassian_mcp_server/server.py

{ "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" } } } }

{ "$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/" ] }

{ "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" } } } }

For GitHub Copilot Chat with MCP support, add to workspace settings:

{ "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" } } } }

{ "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" } } }

For security, set environment variables instead of hardcoding in config files:

# 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"

{ "env": { "ATLASSIAN_SITE_URL": "${ATLASSIAN_SITE_URL}", "ATLASSIAN_CLIENT_ID": "${ATLASSIAN_CLIENT_ID}", "ATLASSIAN_CLIENT_SECRET": "${ATLASSIAN_CLIENT_SECRET}" } }

- Start the MCP server
- Use theauthenticate_atlassiantool to begin OAuth flow
- Browser opens automatically to Atlassian login
- After authorization, authentication completes automatically
- Credentials are saved locally for future use

- authenticate_atlassian()- Start seamless OAuth authentication flow

- 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_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

- 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

- confluence_search_content(query, limit=25, space_id=None)- Advanced content search
- confluence_get_page_children(page_id, limit=25)- Get child pages

- 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

- 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

- confluence_get_page_attachments(page_id, limit=25)- Get page attachments
- confluence_get_attachment(attachment_id)- Get attachment details

- confluence_get_page_versions(page_id, limit=25)- Get page version history
- confluence_get_page_version(page_id, version_number)- Get specific page version

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

- 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

- 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

- 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)

- 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

This MCP server usesminimal required scopesfollowing the principle of least privilege:

- 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

- manage:*scopes - Only for administrative operations

This MCP server usesgranular scopesfor 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(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.

This project implements comprehensive supply chain security measures:

- 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 indocs/DEPENDENCIES.md
- Regular Updates: Weekly automated security checks via GitHub Actions

# 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

- 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

- FastMCP: Modern MCP server framework
- httpx: Async HTTP client
- Pydantic: Data validation and settings management

MIT License - see LICENSE file for details.