Mcp Server Atlassian Server

Mcp Server Atlassian Server is an MCP bridge that provides AI assistants with direct access to Atlassian products including Bitbucket Cloud repositories, pull requests, workspaces, and code review workflows. This server implements the Model Context Protocol to enable real-time interaction with your Atlassian development infrastructure, allowing language models to read repository data, review pull requests, and navigate workspace structures programmatically.

When to Use This MCP Server

Connect this server when...

• You want AI assistance reviewing pull requests, understanding code changes, and drafting review comments in Bitbucket
• Your team uses Atlassian Bitbucket for source control and you need conversational access to repository data
• You are building automated code review workflows that leverage AI to analyze diffs and suggest improvements
• You need to search across multiple Bitbucket repositories and workspaces to find specific code patterns or files
• You want to streamline developer workflows by enabling AI to read commit histories and branch information

Consider alternatives when...

• Your repositories are hosted on GitHub or GitLab, which have their own dedicated MCP servers
• You only need local git operations without interacting with the Bitbucket cloud API
• You require write access to create repositories or merge pull requests through automation

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
    }
  }
}

Connection setup:

1. Ensure Node.js 18+ is installed on your system
2. Create an Atlassian API token at id.atlassian.com/manage-profile/security/api-tokens
3. Set environment variables: ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN
4. Add the configuration above to your .mcp.json file and restart your MCP client

Example tool usage:

# List repositories in a workspace
> Show me all repositories in the "my-team" Bitbucket workspace

# Review a pull request
> Summarize the changes in pull request #42 on the backend-api repository

# Search for code patterns
> Find all files containing "deprecated" annotations in the main branch of our core-library repo

Core Concepts

Concept	Purpose	Details
Workspaces	Organization-level grouping	Bitbucket workspaces contain repositories, members, and permissions that scope all operations
Repositories	Source code containers	Git repositories within a workspace that hold branches, commits, pull requests, and file content
Pull Requests	Code review workflow	Structured code change proposals with diffs, comments, approvals, and merge status tracking
API Token Auth	Secure access	Atlassian API tokens paired with email provide authenticated access without exposing passwords
Branch Navigation	Code exploration	Tools to browse branches, view commit history, and compare changes across different refs

Architecture:

+------------------+       +------------------+       +------------------+
|  Atlassian       |       |  Atlassian MCP   |       |  AI Assistant    |
|  Bitbucket Cloud |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  REST API        | HTTPS |  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+------------------------------------------+
| Workspaces > Repos > PRs > Code > Diffs  |
+------------------------------------------+

Configuration

Parameter	Type	Default	Description
ATLASSIAN_EMAIL	string	(required)	Email address associated with your Atlassian account for API authentication
ATLASSIAN_API_TOKEN	string	(required)	API token generated from your Atlassian account security settings
ATLASSIAN_BASE_URL	string	https://api.bitbucket.org	Base URL for the Bitbucket Cloud API endpoint
workspace	string	(auto-detect)	Default workspace slug to scope operations when not explicitly specified
page_size	integer	25	Number of results returned per page for list operations on repositories and PRs

Best Practices

1. Use workspace-scoped API tokens. Generate API tokens that are scoped to specific workspaces rather than granting organization-wide access. This limits the blast radius if a token is compromised and follows the principle of least privilege for AI assistant access.

2. Filter pull request queries by state. When reviewing pull requests, always specify the desired state (open, merged, declined) to avoid retrieving the entire PR history. Large repositories can have thousands of closed PRs, and unfiltered queries will be slow and return excessive data.

3. Leverage diff context for code reviews. When asking the AI to review a pull request, request the full diff context rather than just file names. The MCP server provides complete diff data including added, removed, and modified lines, which enables substantive code review feedback.

4. Cache workspace and repository metadata. If you frequently work with the same set of repositories, establish the workspace context at the beginning of your session. This avoids repeated API calls to resolve workspace and repository identifiers for each subsequent operation.

5. Combine with local git for write operations. Use this MCP server for reading Bitbucket data and reviewing code, then use your local git CLI for push, merge, and branch operations. This separation ensures the AI assistant has read access for analysis while write operations go through your normal authenticated git workflow.

Common Issues

"401 Unauthorized" errors on connection. Verify that your ATLASSIAN_EMAIL matches the email on your Atlassian account and that the API token has not expired. Regenerate the token from id.atlassian.com/manage-profile/security/api-tokens and update your environment variables. Ensure there are no trailing spaces in the token value.

Repository not found despite correct name. Bitbucket uses workspace/repo-slug format for repository identification. Ensure you are specifying the repository slug (URL-friendly name) rather than the display name. Check the repository URL in your browser to confirm the correct slug.

Slow responses when listing large workspaces. Workspaces with hundreds of repositories can produce slow list operations. Use search filters and pagination parameters to narrow results. Specify the repository name directly when possible rather than listing all repositories and filtering client-side.