Skip to main content

Atlassian Platform MCP Server

Create a powerful Model Context Protocol (MCP) server for Atlassian Platform in minutes with our AI Gateway. This guide walks you through setting up seamless integration with Atlassian's suite of collaboration tools and instant OAuth authentication.

About Atlassian Platform API​

The Atlassian Platform provides unified access to multiple Atlassian cloud products including Jira, Confluence, Bitbucket, and more. The API enables comprehensive integration across the entire Atlassian ecosystem with consistent authentication and user management.

Key Capabilities​

  • Unified Authentication: Single sign-on across products
  • User Management: Centralized user and group control
  • Cross-Product Integration: Seamless data flow
  • Organization Admin: Manage multiple sites
  • App Development: Forge platform for custom apps
  • Webhooks: Real-time event notifications
  • Audit Logs: Comprehensive activity tracking
  • Data Residency: Regional data control

API Features​

  • OAuth 2.0: Secure authentication
  • REST APIs: Consistent interface
  • GraphQL: Flexible data queries
  • Forge Runtime: Serverless functions
  • Rate Limiting: Fair usage policies
  • Batch Operations: Bulk updates
  • Async Processing: Long-running tasks
  • Multi-tenancy: Site isolation

What You Can Do with Atlassian Platform MCP Server​

The MCP server transforms Atlassian Platform API into a natural language interface, enabling AI agents to:

User & Organization Management​

  • User Operations

    • "Create new user account"
    • "Deactivate user access"
    • "Update user profile"
    • "Manage user permissions"

  • Group Management

    • "Create development team group"
    • "Add users to group"
    • "Set group permissions"
    • "List group members"

  • Organization Admin

    • "List all sites"
    • "Manage site access"
    • "Configure policies"
    • "Monitor usage"

Cross-Product Operations​

  • Jira Integration

    • "Create issue from Confluence page"
    • "Link commits to Jira issues"
    • "Sync project documentation"
    • "Track development progress"

  • Confluence Integration

    • "Create meeting notes page"
    • "Update documentation"
    • "Share knowledge base"
    • "Manage permissions"

  • Bitbucket Integration

    • "Create pull request"
    • "Link to Jira issue"
    • "Manage repositories"
    • "Configure pipelines"

Site Administration​

  • Site Management

    • "List managed sites"
    • "Configure site settings"
    • "Manage products"
    • "Control access"

  • Security Settings

    • "Enable two-factor auth"
    • "Configure SSO"
    • "Set IP allowlist"
    • "Manage API tokens"

  • Compliance

    • "Export audit logs"
    • "Data residency settings"
    • "Privacy controls"
    • "Retention policies"

Analytics & Insights​

  • Usage Analytics

    • "Show active users"
    • "Product adoption rates"
    • "Storage consumption"
    • "License utilization"

  • Activity Monitoring

    • "Recent admin actions"
    • "Security events"
    • "Failed login attempts"
    • "API usage stats"

App Management​

  • Forge Apps

    • "Deploy custom app"
    • "Manage app permissions"
    • "Monitor app usage"
    • "Update app config"

  • Marketplace Apps

    • "Install marketplace app"
    • "Configure app settings"
    • "Manage subscriptions"
    • "Review app permissions"

Automation & Workflows​

  • Cross-Product Automation

    • "Sync Jira to Confluence"
    • "Auto-create documentation"
    • "Update multiple products"
    • "Trigger workflows"

  • Event Handling

    • "Subscribe to webhooks"
    • "Process events"
    • "Route notifications"
    • "Log activities"

Prerequisites​

  • Access to Cequence AI Gateway
  • Atlassian Cloud account with admin access
  • OAuth 2.0 app registration
  • Organization admin permissions (recommended)

Step 1: Configure Atlassian Platform Access​

1.1 Create OAuth 2.0 App​

  1. Go to developer.atlassian.com
  2. Navigate to Console Create app
  3. Choose OAuth 2.0 integration
  4. Configure app details:
    • App name: "AI Gateway Integration"
    • App description: "Integration with AI Gateway"
    • Permissions: Select required scopes

1.2 Configure OAuth Settings​

  1. In app settings, go to Authorization
  2. Add callback URL from AI Gateway
  3. Configure scopes:
    • read:jira-user - Read Jira users
    • read:confluence-content.all - Read Confluence
    • read:bitbucket - Read Bitbucket
    • Additional scopes as needed

1.3 Get Credentials​

Note down:

  • Client ID
  • Client Secret
  • Authorization URL
  • Token URL

1.4 Configure Permissions​

Essential scopes for cross-product access:

  • User management scopes
  • Product-specific read/write scopes
  • Admin scopes (if needed)
  • Webhook scopes

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find Atlassian Platform API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: https://api.atlassian.com
  2. Products: Select Jira, Confluence, Bitbucket
  3. API Version: Latest stable
  4. Click Next

Step 6: MCP Server Configuration​

  1. Name: "Atlassian Platform"
  2. Description: "Unified Atlassian integration"
  3. Timeout: 60 seconds
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: OAuth 2.0 (3LO)
  2. Authorization URL: https://auth.atlassian.com/authorize
  3. Token URL: https://auth.atlassian.com/oauth/token
  4. Client ID & Secret: From app registration
  5. Scopes: Configure required scopes

Available Atlassian Platform API Scopes​

User Management​

  • Basic Access
    • read:me - Read own profile
    • read:account - Read user accounts
    • manage:jira-configuration - Manage Jira

Jira Scopes​

  • Issues & Projects
    • read:jira-work - Read issues
    • write:jira-work - Create/update issues
    • delete:jira-work - Delete issues

Confluence Scopes​

  • Content Management
    • read:confluence-content.all - Read all content
    • write:confluence-content - Create/update content
    • delete:confluence-content - Delete content

Bitbucket Scopes​

  • Repository Access
    • repository:read - Read repositories
    • repository:write - Write to repos
    • pullrequest:write - Manage PRs

Admin Scopes​

  • Organization
    • read:organization - Read org data
    • write:organization - Manage org
    • read:audit-log - Access audit logs

Step 8-10: Complete Setup​

Configure security settings, choose deployment options, and deploy your server.

Using Your Atlassian Platform MCP Server​

With Claude Desktop​

{
  "servers": {
    "atlassian": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "oauth2",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "cloud_id": "your-cloud-id"
      }
    }
  }
}

Natural Language Commands​

  • "Create a Jira issue for the bug in Confluence page"
  • "List all active users across our Atlassian products"
  • "Create a Confluence page from this Jira epic"
  • "Show pull requests linked to PROJ-123"
  • "Set up automation to sync Jira issues to Confluence"

API Integration Example​

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret'
  }
});

// Get accessible resources
const resources = await mcpClient.atlassian.getAccessibleResources();
console.log(`Access to ${resources.length} Atlassian sites`);

const primarySite = resources[0];
const cloudId = primarySite.id;

// User management across products
const user = await mcpClient.atlassian.createUser({
  email: 'newuser@company.com',
  displayName: 'John Smith',
  products: [
    { productKey: 'jira-software' },
    { productKey: 'confluence' }
  ],
  sendEmail: true
});

console.log(`Created user: ${user.accountId}`);

// Cross-product: Create Jira issue from Confluence content
const confluencePage = await mcpClient.atlassian.confluence.getPage({
  cloudId: cloudId,
  pageId: 'page-123456'
});

const jiraIssue = await mcpClient.atlassian.jira.createIssue({
  cloudId: cloudId,
  fields: {
    project: { key: 'PROJ' },
    summary: `Action items from: ${confluencePage.title}`,
    description: {
      type: 'doc',
      version: 1,
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'Created from Confluence page: '
            },
            {
              type: 'inlineCard',
              attrs: {
                url: confluencePage._links.webui
              }
            }
          ]
        }
      ]
    },
    issuetype: { name: 'Task' },
    labels: ['from-confluence', 'action-items']
  }
});

// Link the Confluence page to Jira issue
await mcpClient.atlassian.confluence.createPageProperty({
  cloudId: cloudId,
  pageId: confluencePage.id,
  key: 'linked-jira-issues',
  value: {
    issues: [jiraIssue.key]
  }
});

// Bitbucket integration: Link PR to Jira issue
const pullRequest = await mcpClient.atlassian.bitbucket.createPullRequest({
  cloudId: cloudId,
  workspace: 'company-workspace',
  repo_slug: 'main-app',
  title: `Fix for ${jiraIssue.key}: ${jiraIssue.fields.summary}`,
  source: {
    branch: { name: `feature/${jiraIssue.key}` }
  },
  destination: {
    branch: { name: 'main' }
  },
  description: `This PR addresses ${jiraIssue.key}\n\nChanges:\n- Fixed the bug\n- Added tests`,
  close_source_branch: true
});

// Organization management
const orgUsers = await mcpClient.atlassian.admin.listOrganizationUsers({
  organizationId: 'org-123456',
  limit: 100
});

// Bulk operations
const bulkAddToGroup = await mcpClient.atlassian.admin.bulkAddUsersToGroup({
  organizationId: 'org-123456',
  groupId: 'developers-group',
  users: [
    { accountId: 'user-001' },
    { accountId: 'user-002' },
    { accountId: 'user-003' }
  ]
});

// Cross-product search
const searchResults = await mcpClient.atlassian.search({
  cloudId: cloudId,
  query: 'project roadmap',
  entities: ['jira-issue', 'confluence-page', 'bitbucket-pr']
});

console.log('Search Results:');
searchResults.results.forEach(result => {
  console.log(`${result.entityType}: ${result.title}`);
});

// Automation: Sync Jira project to Confluence space
const automationRule = await mcpClient.atlassian.automation.createRule({
  name: 'Sync Jira to Confluence',
  trigger: {
    type: 'jira:issue_created',
    project: 'PROJ'
  },
  actions: [
    {
      type: 'confluence:create_page',
      space: 'PROJDOCS',
      parent: 'project-issues',
      title: '{{issue.summary}}',
      body: `
        h2. Issue Details
        * *Key*: {{issue.key}}
        * *Type*: {{issue.type}}
        * *Priority*: {{issue.priority}}
        * *Assignee*: {{issue.assignee}}
        
        h2. Description
        {{issue.description}}
      `
    },
    {
      type: 'jira:add_comment',
      body: 'Documentation page created: {{confluence.page.url}}'
    }
  ]
});

// Site administration
const siteConfig = await mcpClient.atlassian.admin.updateSiteConfiguration({
  cloudId: cloudId,
  settings: {
    twoFactorAuthentication: 'required',
    publicSignup: false,
    ipAllowlist: ['192.168.1.0/24', '10.0.0.0/8'],
    sessionTimeout: 8 * 60 * 60 * 1000, // 8 hours
    apiTokenAccess: true
  }
});

// Audit log retrieval
const auditEvents = await mcpClient.atlassian.admin.getAuditLog({
  organizationId: 'org-123456',
  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // Last 7 days
  categories: ['security', 'user_management'],
  limit: 1000
});

console.log(`Found ${auditEvents.total} audit events`);

// Forge app deployment
const forgeApp = await mcpClient.atlassian.forge.deployApp({
  appId: 'custom-integration-app',
  environment: 'production',
  manifest: {
    modules: {
      jira: {
        globalPage: [
          {
            key: 'analytics-dashboard',
            title: 'Analytics Dashboard',
            location: 'system.top.navigation.bar'
          }
        ]
      },
      confluence: {
        macro: [
          {
            key: 'jira-issues-macro',
            title: 'Jira Issues',
            description: 'Display Jira issues in Confluence'
          }
        ]
      }
    },
    permissions: {
      scopes: [
        'read:jira-work',
        'read:confluence-content.all'
      ]
    }
  }
});

// License management
const licenses = await mcpClient.atlassian.admin.getOrganizationLicenses({
  organizationId: 'org-123456'
});

licenses.products.forEach(product => {
  console.log(`${product.name}: ${product.activeUsers}/${product.licensedUsers} users`);
});

// Data residency configuration
const dataResidency = await mcpClient.atlassian.admin.updateDataResidency({
  organizationId: 'org-123456',
  location: 'EU', // EU, US, etc.
  products: ['jira-software', 'confluence']
});

// Webhook subscription for cross-product events
const webhook = await mcpClient.atlassian.webhooks.create({
  name: 'Cross-Product Event Handler',
  url: 'https://your-app.com/webhooks/atlassian',
  events: [
    'jira:issue_created',
    'jira:issue_updated',
    'confluence:page_created',
    'confluence:page_updated',
    'bitbucket:pullrequest_created',
    'bitbucket:pullrequest_merged'
  ],
  filters: {
    'jira:issue_created': {
      projects: ['PROJ', 'TEAM']
    }
  }
});

// Handle webhook events
app.post('/webhooks/atlassian', async (req, res) => {
  const { event, data } = req.body;
  
  switch (event) {
    case 'jira:issue_created':
      // Auto-create Confluence documentation
      if (data.issue.issuetype.name === 'Epic') {
        await createConfluenceSpaceForEpic(data.issue);
      }
      break;
      
    case 'bitbucket:pullrequest_merged':
      // Auto-resolve linked Jira issues
      const linkedIssues = extractJiraIssues(data.pullrequest.title);
      for (const issueKey of linkedIssues) {
        await transitionIssueToResolved(issueKey);
      }
      break;
  }
  
  res.status(200).send('OK');
});

Common Use Cases​

Unified User Management​

  • Centralized user provisioning
  • Cross-product permissions
  • Bulk user operations
  • Access auditing

Cross-Product Integration​

  • Jira-Confluence sync
  • Bitbucket-Jira linking
  • Automated workflows
  • Data consistency

Administrative Operations​

  • Organization management
  • Security configuration
  • License optimization
  • Compliance reporting

Development Workflows​

  • Issue tracking integration
  • Documentation automation
  • Code review linking
  • Release management

Best Practices​

  1. Authentication:

    • Use OAuth 2.0 for user context
    • Implement token refresh
    • Store tokens securely
    • Handle scope changes

  2. API Usage:

    • Respect rate limits
    • Use batch operations
    • Cache frequently accessed data
    • Handle pagination properly

  3. Cross-Product Operations:

    • Maintain data consistency
    • Handle async operations
    • Implement error recovery
    • Log integration activities

Troubleshooting​

Common Issues​

  1. Authentication Errors

    • Verify OAuth app configuration
    • Check scope permissions
    • Validate redirect URLs
    • Review token expiration

  2. Cross-Product Issues

    • Ensure products are enabled
    • Verify user has access
    • Check product-specific limits
    • Validate cloud IDs

  3. Rate Limiting

    • Monitor rate limit headers
    • Implement exponential backoff
    • Use webhooks for real-time data
    • Cache API responses

Getting Help​