Bitbucket MCP Server - Enterprise Secure Edition

Secure, self-hosted Model Context Protocol (MCP) server for Bitbucket Server/Data Center — designed for enterprise, air-gapped, and private network environments. Built in Rust for maximum security, performance, and zero runtime dependencies.

---

🎯 Why This MCP Server?

Feature	This Server	Other MCP Servers
Deployment	Single binary	Node.js + npm dependencies
Security	Rust memory safety	JavaScript runtime vulnerabilities
Dependencies	Zero at runtime	100+ npm packages
Air-gapped	✅ Fully supported	❌ Requires npm registry
SSL/TLS	Custom CA support	Limited
Permissions	Granular READ/WRITE/DELETE	All-or-nothing
Audit Trail	Security-audited dependencies	Supply chain risks

Perfect For:

• 🔒 Enterprise environments with strict security policies
• 🏢 Corporate networks behind firewalls
• ✈️ Air-gapped systems without internet access
• 🛡️ Compliance requirements (SOC2, ISO27001, GDPR)
• 📦 Minimal attack surface requirements

---

🚀 Quick Start

Install (30 seconds)

# Global install
npm install -g @bitbucket-mcp/server

# Or run without install
npx @bitbucket-mcp/server

Configure Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@bitbucket-mcp/server"],
      "env": {
        "BITBUCKET_BASE_URL": "https://bitbucket.your-company.com",
        "BITBUCKET_USERNAME": "service-account",
        "BITBUCKET_PASSWORD": "your-personal-access-token",
        "BITBUCKET_SSL_VERIFY": "true",
        "BITBUCKET_ALLOW_READ": "true",
        "BITBUCKET_ALLOW_WRITE": "false",
        "BITBUCKET_ALLOW_DELETE": "false"
      }
    }
  }
}

---

🔐 Security Features

Enterprise-Grade Security

Feature	Description
Memory Safety	Rust prevents buffer overflows, use-after-free, data races
Zero Supply Chain Risk	No runtime npm dependencies to compromise
Audited Dependencies	All Rust crates scanned with cargo-audit
Granular Permissions	Separate READ/WRITE/DELETE controls
Self-Signed SSL	Support for internal CA certificates
No Telemetry	Zero data collection, fully offline-capable

Security Configuration

{
  "env": {
    // Require SSL verification (default: true)
    "BITBUCKET_SSL_VERIFY": "true",
    
    // Read-only mode for maximum security
    "BITBUCKET_ALLOW_READ": "true",
    "BITBUCKET_ALLOW_WRITE": "false",
    "BITBUCKET_ALLOW_DELETE": "false",
    
    // Use personal access token instead of password
    "BITBUCKET_PASSWORD": "your-pat-token"
  }
}

Compliance Ready

• ✅ SOC2: Audit trails, access controls, encryption in transit
• ✅ ISO27001: Secure development, dependency management
• ✅ GDPR: No data retention, on-premise deployment
• ✅ HIPAA: Private network deployment supported

---

🛠️ Available Tools (19 MCP Tools)

Projects

Tool	Description	Permission
list_projects	List all projects with pagination	READ
get_project	Get project details by key	READ

Repositories

Tool	Description	Permission
list_repos	List repositories in a project	READ
get_repo	Get repository details	READ

Pull Requests

Tool	Description	Permission
list_prs	List pull requests with filters (state, author)	READ
get_pr	Get pull request details	READ
create_pr	Create a new pull request	WRITE
update_pr	Update pull request title/description	WRITE
merge_pr	Merge a pull request	DELETE
decline_pr	Decline a pull request	DELETE
pr_diff	Get pull request diff	READ
pr_changes	Get pull request file changes	READ

Branches

Tool	Description	Permission
list_branches	List repository branches	READ
create_branch	Create a new branch from ref	WRITE
compare_branches	Compare commits between branches	READ

Commits

Tool	Description	Permission
list_commits	List repository commits with filters	READ
get_commit	Get commit details	READ

Files

Tool	Description	Permission
list_files	Browse repository files	READ
get_file_content	Get file content at specific commit	READ

---

📦 Deployment Options

Option 1: NPM (Recommended)

npm install -g @bitbucket-mcp/server

Option 2: Direct Binary (Air-Gapped)

Download prebuilt binary for your platform:

Platform	Binary	Size
macOS Intel	bitbucket-mcp-darwin-x64	~15 MB
macOS ARM	bitbucket-mcp-darwin-arm64	~12 MB
Linux x64	bitbucket-mcp-linux-x64	~18 MB
Linux ARM64	bitbucket-mcp-linux-arm64	~16 MB
Windows x64	bitbucket-mcp-win32-x64.exe	~20 MB

# Download and run
chmod +x bitbucket-mcp-linux-x64
./bitbucket-mcp-linux-x64

Option 3: Docker (Coming Soon)

FROM scratch
COPY bitbucket-mcp-linux-x64 /bitbucket-mcp
ENTRYPOINT ["/bitbucket-mcp"]

---

🏢 Enterprise Deployment

Air-Gapped Installation

1. Download on internet-connected machine:

   npm pack @bitbucket-mcp/server

2. Transfer to air-gapped system via secure media

3. Install offline:

   npm install -g bitbucket-mcp-server-0.1.0.tgz

Corporate Proxy Support

{
  "env": {
    "BITBUCKET_BASE_URL": "https://bitbucket.internal.company.com",
    "HTTP_PROXY": "http://proxy.company.com:8080",
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.internal.company.com"
  }
}

Service Account Setup

# 1. Create dedicated service account in Bitbucket
# 2. Grant minimal required permissions
# 3. Generate Personal Access Token (PAT)
# 4. Use in configuration (never commit to git!)

---

🔧 Configuration Reference

Environment Variables

Variable	Required	Default	Description
BITBUCKET_BASE_URL	Yes	-	Bitbucket Server base URL
BITBUCKET_API_KEY	No	-	API Key / PAT for Bearer token authentication (has priority over Basic Auth)
BITBUCKET_USERNAME	Yes	-	Username for Basic Auth (ignored if BITBUCKET_API_KEY is set)
BITBUCKET_PASSWORD	Yes	-	Password or PAT for Basic authentication (ignored if BITBUCKET_API_KEY is set)
BITBUCKET_SSL_VERIFY	No	true	SSL certificate verification
BITBUCKET_ALLOW_READ	No	true	Allow read operations
BITBUCKET_ALLOW_WRITE	No	true	Allow write operations
BITBUCKET_ALLOW_DELETE	No	true	Allow delete operations

Permission Modes

// Read-only (maximum security)
{ "BITBUCKET_ALLOW_READ": "true", "BITBUCKET_ALLOW_WRITE": "false", "BITBUCKET_ALLOW_DELETE": "false" }

// Developer mode (no delete)
{ "BITBUCKET_ALLOW_READ": "true", "BITBUCKET_ALLOW_WRITE": "true", "BITBUCKET_ALLOW_DELETE": "false" }

// Admin mode (full access)
{ "BITBUCKET_ALLOW_READ": "true", "BITBUCKET_ALLOW_WRITE": "true", "BITBUCKET_ALLOW_DELETE": "true" }

---

🛡️ Security Best Practices

1. Use Personal Access Tokens

# ❌ Don't use password
BITBUCKET_PASSWORD="my-actual-password"

# ✅ Use PAT with minimal scope
BITBUCKET_PASSWORD="pat:read-only-projects-repos"

2. Enable Read-Only Mode

{
  "env": {
    "BITBUCKET_ALLOW_WRITE": "false",
    "BITBUCKET_ALLOW_DELETE": "false"
  }
}

3. Restrict Network Access

# Bind to localhost only (if supported)
# Or use firewall rules to restrict access
sudo ufw allow from 127.0.0.1 to any port 3000

4. Rotate Credentials

# Rotate PAT every 90 days
# Monitor Bitbucket audit logs for unusual activity

5. Enable SSL Verification

{
  "env": {
    "BITBUCKET_SSL_VERIFY": "true"  // Never disable in production
  }
}

---

🐛 Troubleshooting

SSL Certificate Errors

For self-signed/internal CA certificates:

{
  "env": {
    // Option 1: Add to system trust store (recommended)
    // Option 2: Disable verification (NOT recommended for production)
    "BITBUCKET_SSL_VERIFY": "false"
  }
}

⚠️ Warning: Only disable SSL verification for trusted internal servers.

Authentication Failed

# Check credentials
curl -u username:password https://bitbucket.example.com/rest/api/1.0/projects

# Verify PAT has required permissions
# Check user is not locked/suspended

Connection Refused

# Verify URL includes protocol
BITBUCKET_BASE_URL="https://bitbucket.example.com"  # ✅
BITBUCKET_BASE_URL="bitbucket.example.com"          # ❌

# Test connectivity
curl -I https://bitbucket.example.com

# Check firewall/proxy rules

Permission Denied

{
  "env": {
    // Enable only required permissions
    "BITBUCKET_ALLOW_READ": "true",
    "BITBUCKET_ALLOW_WRITE": "false",
    "BITBUCKET_ALLOW_DELETE": "false"
  }
}

---

🏗️ Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│  MCP Server      │────▶│  Bitbucket      │
│  (AI Assistant) │     │  (Rust Binary)   │     │  Server/DC      │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                       │                        │
        │                       │                        │
   User Requests          Zero Dependencies        REST API 1.0
   Natural Language         Memory Safe              Basic Auth
                            Single Binary            SSL/TLS

Why Rust?

• Memory Safety: No buffer overflows, use-after-free, or data races
• Performance: Native code, no GC pauses
• Security: Audited dependencies, minimal attack surface
• Portability: Single static binary, no runtime dependencies

---

📚 Resources

• Model Context Protocol Documentation
• Bitbucket Server REST API
• Security Best Practices
• Enterprise Deployment Guide
• Build Instructions

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

git clone https://github.com/your-org/bitbucket-mcp-server.git
cd bitbucket-mcp-server

# Build
cargo build --release

# Test
cargo test

# Security audit
cargo audit

---

🔄 CI/CD & Automated Releases

Automatic Versioning

При каждом коммите в ветку main автоматически:

1. Dependabot обновляет зависимости (еженедельно по понедельникам)
2. Создается новый тег с инкрементом patch-версии (v0.1.0 → v0.1.1)
3. Генерируется changelog на основе Conventional Commits
4. Публикуется GitHub Release с бинарниками для всех платформ
5. Публикация в npm (при наличии токена NPM_TOKEN)

Conventional Commits

Используйте формат коммитов для автоматического определения типа изменений:

# Новые функции (minor version)
git commit -m "feat: add branch comparison tool"

# Исправления (patch version)
git commit -m "fix: handle SSL certificate errors"

# Обновления зависимостей (patch version)
git commit -m "deps: update tokio to 1.42"

# Документация (не создает релиз)
git commit -m "docs: update README examples"

Workflow Overview

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Push to main   │────▶│  auto-release.yml│────▶│  Create tag     │
│  (non-.md)      │     │                  │     │  (v0.1.0→0.1.1) │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
┌─────────────────┐     ┌──────────────────┐     ┌────────▼────────┐
│  npm Publish    │◀────│  release.yml     │◀────│  GitHub Release │
│                 │     │  Build & Test    │     │  + Changelog    │
└─────────────────┘     └──────────────────┘     └─────────────────┘

Required Secrets

Настройте secrets в GitHub Repository Settings → Secrets → Actions:

Secret	Description	Required
GITHUB_TOKEN	Автоматически создается GitHub	✅ Yes
NPM_TOKEN	Токен для публикации в npm	❌ Optional

Dependabot Configuration

Dependabot автоматически обновляет:

• Rust зависимости (Cargo.toml) — еженедельно
• npm зависимости (package.json) — еженедельно
• GitHub Actions — еженедельно

Все обновления создаются как Pull Request с лейблами:

• dependencies + rust / javascript / ci/cd
• Группированные обновления для minor/patch версий

---

📄 License

MIT License - see LICENSE file for details.

---

🔍 Keywords

MCP server, Model Context Protocol, Bitbucket Server, Bitbucket Data Center, enterprise MCP, secure MCP, self-hosted MCP, air-gapped MCP, on-premise MCP, single binary MCP, Rust MCP server, zero dependencies, private network MCP, corporate MCP, SOC2 compliant, ISO27001 compliant, Atlassian integration, Bitbucket REST API, Claude Desktop MCP, AI integration

---

Built for enterprise security • Zero runtime dependencies • Air-gapped ready