Atlassian MCP Server

Model Context Protocol (MCP) server for Atlassian tools (Jira, Confluence, and Bitbucket).

Enterprise-grade MCP server providing 102 production-ready tools for Jira, Confluence, and Bitbucket

• ✨ Works with Amazon Q Developer, Claude, Cursor, and more
• 🚀 Deploy locally or to AWS Lambda
• 🔒 Enterprise security built-in
• 🎫 Ticket Support Agent with 6 specialized tools

Quick Links

• 🚀 Quick Start - Get running in 5 minutes
• 📖 Understanding MCP - Learn how MCP works
• 🤖 AI Agent Setup - Connect to Amazon Q, Claude, Cursor, etc.
• ☁️ AWS Deployment - Deploy to Lambda
• 📊 Monitoring - CloudWatch metrics and alerts
• 🏗️ Architecture - System design and components

Quick Start

Local Development:

pip install -r mcp_server/requirements.txt
cp config.template.yaml config.yaml
# Edit config.yaml with your credentials
python mcp_server/main.py

Configuration Examples:

Cloud:

deployment_type: cloud
cloud:
  atlassian_base_url: https://yourcompany.atlassian.net
  atlassian_username: your-email@company.com
  atlassian_api_token: your-token
  bitbucket_workspace: your-workspace
  bitbucket_api_token: your-token

Data Center:

deployment_type: datacenter
datacenter:
  jira_base_url: https://jira.company.com
  jira_pat_token: your-token
  confluence_base_url: https://wiki.company.com
  confluence_pat_token: your-token
  bitbucket_base_url: https://git.company.com
  bitbucket_pat_token: your-token
  bitbucket_project: PROJECT_KEY

AWS Deployment:

cp config.template.yaml config.yaml
# Edit config.yaml with your credentials
python deploy.py

Features

• Jira (31 tools): Issues, comments, transitions, attachments, attachment upload, users, worklogs, labels, issue linking, advanced search, priority management, agile boards, sprints, user permissions
• Confluence (31 tools): Pages, spaces, comments, attachments, search, users, user lookup by userkey, labels, page history, permissions, page copying, user content, recent content, version restore, search by author/label, page hierarchy (move, children, descendants, ancestors), CQL search
• Bitbucket (34 tools): Repositories, pull requests, commits, branches, diffs, file search, reviewers, branch management, PR activity, default reviewers, author filtering, change requests, branch restrictions, build status, webhooks
• Ticket Support Agent (6 tools): Open ticket triage, template validation, assignee suggestions, team workload analysis, expertise JQL construction, troubleshooting doc lookup
• Flexible Credentials: Configure only the services you need
• Dual Platform: Supports both Cloud and Data Center deployments
• AWS Ready: Deploy as Lambda function with API Gateway

Prerequisites

Local Development:

• Python 3.11+
• Atlassian account (Cloud or Data Center)
• API tokens for services you want to use

AWS Deployment (optional):

• AWS CLI configured with credentials
• AWS SAM CLI installed (installation guide)

Generate Tokens:

• Cloud: https://id.atlassian.com/manage-profile/security/api-tokens
• Bitbucket Cloud: https://bitbucket.org/account/settings/app-passwords/
• Data Center: Profile → Personal Access Tokens

Configuration

AWS Deployment

1. Copy the template:

cp config.template.yaml config.yaml

2. Edit config.yaml with your credentials:

For Cloud:

deployment_type: cloud
cloud:
  atlassian_base_url: https://yourcompany.atlassian.net
  atlassian_username: your-email@company.com
  atlassian_api_token: your-token
  bitbucket_workspace: your-workspace  # optional
  bitbucket_api_token: your-token      # optional

For Data Center:

deployment_type: datacenter
datacenter:
  jira_base_url: https://jira.company.com
  jira_pat_token: your-token
  confluence_base_url: https://wiki.company.com
  confluence_pat_token: your-token
  bitbucket_base_url: https://git.company.com
  bitbucket_pat_token: your-token
  bitbucket_project: PROJECT_KEY

3. Deploy:

python deploy.py

Local Development

For local development, use config.yaml (same format as AWS deployment):

cp config.template.yaml config.yaml
# Edit config.yaml with your credentials and optional ticket support agent config
python mcp_server/main.py

Note: The server loads configuration from config.yaml automatically. Environment variables can be used as an alternative if config.yaml is not present, but using config.yaml is the recommended approach for consistency with AWS deployment.

Platform Detection: The server automatically detects whether to use Cloud or Data Center APIs in this order:

1. DEPLOYMENT_TYPE environment variable (cloud or datacenter)
2. deployment_type field in config.yaml
3. Presence of Data Center credentials (PAT tokens)
4. Defaults to Cloud if none of the above

AI Agent Integration

Integrate with popular AI agents and development tools:

Amazon Q Developer:

{
  "mcpServers": {
    "atlassian-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server/main.py"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourcompany.atlassian.net",
        "ATLASSIAN_USERNAME": "your-email@company.com",
        "ATLASSIAN_API_TOKEN": "your-token"
      }
    }
  }
}

Also supports: Claude Desktop, Cline (VS Code), Cursor, Continue, Zed Editor

See AGENT_INTEGRATION.md for complete setup instructions.

AWS Deployment

1. Configure credentials:

cp config.template.yaml config.yaml
# Edit config.yaml with your Atlassian credentials

2. Deploy:

python deploy.py

The script will:

• Build the SAM application
• Deploy to AWS with your credentials
• Display the MCP API URL

See DEPLOYMENT_GUIDE.md for detailed instructions.

Testing

Unit Tests:

pip install -r requirements-dev.txt
pytest tests/unit/

Integration Tests:

Cloud (tests with real credentials):

python tests/cloud/test_all_cloud_tools.py

Data Center (tests with real credentials):

python tests/datacenter/test_all_dc_tools.py

Common/Agent tools (tests with real credentials):

python tests/common/test_all_common_tools.py

Test Features:

• Comprehensive unit test coverage
• Integration tests for core workflows
• Verbose output showing results

Monitoring

CloudWatch integration with:

• Structured JSON logging
• Custom metrics (tool usage, duration)
• Automatic alarms (errors, throttles, slow responses)
• Dashboard for visualization

See MONITORING.md for setup and configuration.

Documentation

• MCP_OVERVIEW.md - Understanding MCP and how this server works
• AGENT_INTEGRATION.md - AI agent integration (Claude, Cursor, Cline, etc.)
• DEPLOYMENT_GUIDE.md - AWS deployment and configuration
• TESTING.md - Comprehensive testing guide
• TICKET_SUPPORT_AGENT.md - Ticket support agent tools
• MONITORING.md - CloudWatch setup and alerts
• ARCHITECTURE.md - System architecture and design

API Documentation

• Jira Cloud
• Confluence Cloud
• Bitbucket Cloud
• Jira Data Center
• Confluence Data Center
• Bitbucket Data Center

Security

• IAM authentication for same-account access
• Rate limiting (100 req/sec, 200 burst)
• Encrypted credentials in Lambda environment variables
• HTTPS-only traffic
• config.yaml gitignored (credentials not in version control)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on the Model Context Protocol specification
• Integrates with Atlassian Cloud and Data Center APIs
• Designed for Amazon Q Developer and other MCP-compatible AI assistants