Connect your AI coding tools to Bitbucket Cloud

Connect your AI coding tool to Bitbucket Cloud to give your AI agent the context it needs to summarize changes in a repository, help review a pull request, or investigate a failed build within a pipeline. You can connect your AI coding tool by using Teamwork Graph CLI (TWG CLI) or Atlassian MCP. If your agent is also connected to Jira and Confluence, it can retrieve requirements and related documentation while working in your repository.

Choose an integration

You can use either integration with a compatible local coding agent, and you can configure both. Refer to the following for more details on which integration will work best for you and your team: Compare TWG CLI and Atlassian MCP.

Prerequisites

• An Atlassian account with access to the Bitbucket workspace and repositories you want to use.

• An AI coding tool that supports terminal commands for TWG CLI, or MCP connections for Atlassian MCP.

• Access to the relevant Jira site or Confluence content if you want your agent to use context from those apps.

For Atlassian MCP, your Bitbucket workspace must be linked to an Atlassian organization. You will not be able to select workspaces that are not linked to an organization during authorization. Ask your administrator to link the workspace to an organization if needed. See the Bitbucket MCP requirements and supported actions for more details.

Set up TWG CLI

Install TWG CLI

To install through your coding agent, paste this prompt into the agent:

Alternatively, you can install this from a terminal.

macOS and Linux

Windows

The installer guides you through your Atlassian login, configures agent skills, and checks the setup. Follow the browser prompts to choose the resources you want to authorize. For supported operating systems and other installation options, refer to Set up TWG CLI.

Connect your Bitbucket account

When it comes time to configure Bitbucket access during the setup process, follow the terminal prompts. If you’ve already installed TWG CLI, run the following command:

Check your connection

Run the setup health check:

Then test Bitbucket access by listing pull requests. Replace YOUR_WORKSPACE and YOUR_REPOSITORY in the example provided below with your workspace and repository slugs:

An empty list can mean that the repository has no open pull requests. You can now ask your coding agent to use TWG CLI for Bitbucket tasks.

Atlassian also provides TWG CLI plugins for coding agents. These are package setup skills for the local CLI. After installing one, run /twg-setup to install or verify the CLI and log in. The CLI will handle execution and authentication.

Set up Atlassian MCP

Choose a plugin-based setup or configure the MCP server directly in your local client. Both use the Atlassian MCP server.

If your workspace has set up IP allowlisting - be aware that some integration methods will need to be allowlisted.

Install an Atlassian plugin

Claude Code

Install the Atlassian plugin from Claude Marketplace and complete the Atlassian authorization. You can also add Atlassian’s Marketplace directly in Claude Code:

Run /mcp to view the server and authenticate if prompted. Atlassian’s plugin manifest identifies the package, and its MCP configuration uses the v2 endpoint.

Codex

1. Open the plugin directory in Codex and search for Atlassian.

2. Install the plugin published by Atlassian. Note: Some versions list it as Atlassian Rovo.

3. Complete the Atlassian log-in and authorization flow when prompted.

For Claude Desktop and other clients, follow the current Atlassian MCP setup instructions.

Connect directly from a local client

You can configure the Atlassian MCP directly in a local Codex or Claude Code client. This is also useful when a hosted plugin’s network address isn’t permitted by your organization’s IP policy.

Codex

Restart your Codex session after changing the configuration and use the atlassian-mcp-v2 connection for the task. Learn about local Codex MCP configuration.

Claude Code

Open Claude Code and run /mcp to authenticate. For other tools that support a remote HTTP MCP server, use the following:

Complete the browser-based Atlassian login flow. Select the resources you want to authorize and review the requested permissions. OAuth is the recommended method for interactive local integrations. Your organization’s policies may restrict which clients and permissions are available. Learn about MCP authentication.

Check your MCP connection

Ask your agent the following (replace YOUR_WORKSPACE with the name of your actual workspace):

Using Atlassian MCP, list the Bitbucket repositories I can access in workspace YOUR_WORKSPACE.

If your workspace isn’t available, check that it’s linked to an Atlassian organization and that you authorized the correct resources. If you configured both a hosted plugin and a direct local connection, specify which connection your agent should use.

Try a Bitbucket task

Include a repository, pull request, or pipeline URL to help your agent find the right context. For example:

• “Summarize this pull request and identify changes that need closer review: PR_URL.”

• “Show the unresolved comments and tasks on this pull request: PR_URL.”

• “Read the failed step logs for this pipeline and explain the likely cause: PIPELINE_URL.”

• “Prepare a pull request description for these changes.”

Your agent can use the supported Bitbucket actions available to your account and connection.

Implement a Jira work item

When TWG CLI is connected to a Jira site, your coding agent can retrieve work item details alongside Bitbucket context, using your existing permissions. Open your repository in the agent and add the following prompt:

Implement JIRA-123 in this repository. Use TWG CLI to read the Jira work item, its acceptance criteria, comments, and relevant linked documentation. Make the required changes, run the relevant tests, and summarize the implementation.

Note: Replace JIRA-123 with your work item key. If you use multiple Jira sites, include the full work item URL to identify the correct site. TWG CLI supplies the work context; your coding agent performs the implementation. Explore TWG CLI workflows.

Troubleshoot access and IP restrictions

Understand which network makes the request

Hosted integrations can make requests from the provider’s infrastructure. Connecting your computer to an approved corporate VPN may therefore be insufficient. Atlassian documents how IP allowlisting affects MCP access.

OpenAI describes provider egress ranges and local MCP connections. Anthropic separately documents hosted connector networking and local Claude Code plugin execution.

Allow the provider’s published IP ranges

Ask your administrator to review the applicable IP policy and, where appropriate, add the provider’s current published egress ranges.

• For an OpenAI-hosted plugin connection, use the ChatGPT integrations ranges identified in OpenAI’s egress documentation. OpenAI publishes separate ranges for Codex cloud execution; select the ranges matching the connection being used.

• For a Claude hosted connector, consult Anthropic’s networking requirements.

In Bitbucket, administrators manage IP restrictions under workspace access controls. Jira and Confluence have their own application IP policies. Provider ranges can change; use their maintained lists.

Use a direct local connection

Alternatively, configure MCP directly in a local client and run that client from an approved network. Ensure your agent uses the direct connection for the task. The local client’s network address must satisfy the applicable IP policy.

Adding a custom connector in a hosted interface can still use the provider’s cloud network. A direct local connection means configuring the MCP server in the local coding client.

A 403 can have several causes. Confirm the applicable access policy and denial reason before choosing a remedy; the error alone doesn’t establish an IP allowlist problem.

Related documentation