Atlassian Bitbucket MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to interact with Atlassian Bitbucket for pull request reviews, code search, and repository operations.
Features
- Pull Request Management: Review PRs, add/resolve comments, approve changes
- Code Search: Search code across repositories and commits
- Repository Operations: List repos, browse branches, view file content
- Dual Instance Support: Works with both Bitbucket Cloud and self-hosted Data Center/Server
- Secure: Built with security in mind, avoiding compromised npm packages
- Type-Safe: Full TypeScript implementation with strict type checking
- Caching: Smart caching layer for frequently accessed static data
- Local-First: Designed for NPX-based local usage with Personal Access Tokens
Requirements
- Node.js >= 20.0.0
- pnpm (recommended) or npm/yarn
- Bitbucket Personal Access Token (Cloud or Server/Data Center)
- Access to a Bitbucket instance (Cloud or self-hosted)
Quick Start
1. Environment Setup
Copy the example environment file and configure it:
cp .env.example .env
Edit .env and set the required variables:
BITBUCKET_URL=https://bitbucket.org # or your self-hosted URL
BITBUCKET_TOKEN=your_personal_access_token
BITBUCKET_DEFAULT_PROJECT=PROJ # your default project key
2. Installation
pnpm install
3. Build
pnpm run build
4. Usage with MCP Client
Configure your MCP client (e.g., Claude Desktop) to use this server:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["-y", "atlassian-bitbucket-mcp"],
"env": {
"BITBUCKET_URL": "https://bitbucket.org",
"BITBUCKET_TOKEN": "your_token_here",
"BITBUCKET_DEFAULT_PROJECT": "PROJ"
}
}
}
}
Configuration
Environment Variables
All configuration is done through environment variables. See .env.example for the complete list.
Required
BITBUCKET_URL- Your Bitbucket instance URLBITBUCKET_TOKEN- Personal Access TokenBITBUCKET_DEFAULT_PROJECT- Default project key
Optional
BITBUCKET_ALLOWED_ACTIONS- Comma-separated list of allowed tool actionsBITBUCKET_CACHE_ENABLED- Enable/disable caching (default: true)BITBUCKET_CACHE_TTL_REPOS- Repository cache TTL in seconds (default: 3600)- See
.env.examplefor all options
Creating a Personal Access Token
Bitbucket Cloud
- Go to Personal settings > Personal Access Tokens
- Click Create token
- Give it a name and select permissions:
- Repositories: Read, Write
- Pull requests: Read, Write
- Click Create and copy the token
Bitbucket Server/Data Center
- Go to Profile > Manage account > Personal access tokens
- Click Create a token
- Give it a name and select permissions:
- Project permissions: Read
- Repository permissions: Read, Write
- Click Create and copy the token
Available MCP Tools
This server provides the following tools for interacting with Bitbucket:
Pull Request Tools
bitbucket_list_pull_requests- List PRs for a repositorybitbucket_get_pull_request- Get detailed PR informationbitbucket_get_pr_diff- Get PR changes/diffbitbucket_get_pr_commits- Get commits in a PRbitbucket_get_pr_activities- Get PR comments and activitiesbitbucket_add_pr_comment- Add a general commentbitbucket_add_pr_inline_comment- Add inline code commentbitbucket_reply_to_comment- Reply to a commentbitbucket_resolve_comment- Resolve a comment threadbitbucket_update_comment- Edit a commentbitbucket_approve_pr- Approve a pull request
Repository Tools
bitbucket_list_projects- List accessible projectsbitbucket_list_repositories- List repos in a projectbitbucket_get_repository- Get repository detailsbitbucket_get_branches- List repository branchesbitbucket_get_commits- Get commit historybitbucket_get_file_content- Get file content at ref
Code Search Tools
bitbucket_search_code- Search code across repositoriesbitbucket_search_commits- Search commits by message
See docs/TOOLS.md for detailed tool documentation (coming soon).
Development
VSCode Setup (Recommended)
This project includes VSCode workspace settings and extension recommendations. When you open the project in VSCode, you'll be prompted to install:
- ESLint - Code linting
- Prettier - Code formatting
- Markdownlint - Markdown style checking
All formatting and linting happens automatically on save.
Development Commands
# Install dependencies
pnpm install
# Build the project
pnpm run build
# Watch mode for development
pnpm run watch
# Run with local changes
pnpm link --global
# Code quality checks
pnpm run format:all # Format all files
pnpm run lint:all # Lint all files (markdown + code)
pnpm run typecheck # Type check with TypeScript
pnpm run validate # Run all checks (format + lint + typecheck)
Git Hooks
This project uses Husky for Git hooks to maintain code quality and consistency:
Pre-commit Hook
Automatically runs before each commit:
- Prettier - Formats all code
- ESLint - Lints and auto-fixes issues
- TypeScript - Type checks the code
- Build - Ensures project compiles
This ensures all committed code meets quality standards.
Commit Message Hook
- Enforces Conventional Commits format
- Valid formats:
<type>(<optional-scope>): <description> - Allowed types:
feat,fix,docs,style,refactor,test,chore,ci,build,perf,revert - Examples:
feat: add user authenticationfix(auth): resolve login bugdocs: update README
Pre-push Hook
- Validates branch naming convention
- Allowed patterns:
main,master,develop,devfeature/<description>,feat/<description>bugfix/<description>,fix/<description>hotfix/<description>release/<version>chore/<description>,docs/<description>
- Examples:
feature/user-authenticationfix/login-bugrelease/v1.0.0
Project Structure
atlassian-bitbucket-mcp/
├── .husky/ # Git hooks
│ ├── commit-msg # Conventional commits validation
│ ├── pre-commit # Code quality checks
│ └── pre-push # Branch name validation
├── docs/ # Documentation
│ ├── ARCHITECTURE.md # System architecture and design
│ ├── CODING-STANDARDS.md # Coding standards and best practices
│ ├── BRANCH-MANAGEMENT.md # Branch naming and management
│ └── SECURITY.md # Security policy
├── scripts/ # Utility scripts
│ ├── check-package-security.sh
│ ├── pre-commit.sh # Pre-commit validation script
│ ├── pre-push.sh # Pre-push validation script
│ ├── commit-msg.sh # Commit message validation
│ ├── validate-branch-name.sh # Branch name validator
│ └── setup-vscode.sh # VSCode workspace setup
├── types/ # Shared TypeScript type definitions
│ ├── index.ts # Type re-exports
│ ├── bitbucket.ts # Bitbucket API types
│ ├── mcp.ts # MCP protocol types
│ ├── config.ts # Configuration types
│ ├── cache.ts # Cache types
│ ├── logger.ts # Logging types
│ └── common.ts # Common utility types
├── src/ # MCP server implementation
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server setup
│ ├── config.ts # Configuration
│ ├── cache.ts # Caching layer
│ ├── logger.ts # Centralized logging
│ ├── tools/ # MCP tool implementations
│ └── bitbucket/ # Bitbucket API client
├── openapi/ # OpenAPI specifications (future)
│ ├── bitbucket-cloud.yaml
│ └── bitbucket-server.yaml
├── package.json
├── tsconfig.json
└── README.md
Security
This project follows security best practices:
- All dependencies are checked against known compromised packages
- Minimal dependency footprint
- Regular security audits
- See docs/SECURITY.md for detailed security policy
Before Installing Packages
# Check if a package is safe
./scripts/check-package-security.sh <package-name>
License
This project is licensed under the GNU General Public License v3.0.
Documentation
For detailed information about this project, see:
- Architecture Documentation - System architecture, components, and design decisions
- Coding Standards - TypeScript standards, logging, and best practices
- Branch Management - Branch naming conventions and workflow
- Security Policy - Security guidelines and vulnerability reporting
Contributing
Contributions are welcome! Please ensure:
- All new dependencies are verified against compromised package lists
- Code follows the Coding Standards
- Types use
type(notinterface) and are placed intypes/directory - Centralized logger is used at all critical paths
- OpenAPI YAML files are updated alongside type changes
- Tests are included for new features
- Git hooks pass (branch naming, format, lint, typecheck, build)