MCP Bitbucket Python

Overview Schema Related Servers Score Discussions

bb_create_issue

Create issues in Bitbucket repositories with specified title, content, type, and priority. Supports custom workspace and repository slugs, aiding in efficient project tracking and management.

Instructions

Create an issue in a Bitbucket repository

Input Schema

TableJSON Schema

Name	Required	Description	Default
`content`	Yes	Issue content/description
`kind`	No	Issue type (bug, enhancement, proposal, task)	task
`priority`	No	Issue priority (trivial, minor, major, critical, blocker)	minor
`repo_slug`	Yes	Repository slug/name
`title`	Yes	Issue title
`workspace`	No	Repository workspace (defaults to kallows)	kallows

Implementation Reference

src/mcp_bitbucket/server.py:234-270 (schema)

Defines the input schema and description for the bb_create_issue tool in the list_tools handler.

types.Tool(
    name="bb_create_issue",
    description="Create an issue in a Bitbucket repository",
    inputSchema={
        "type": "object",
        "properties": {
            "workspace": {
                "type": "string",
                "description": "Repository workspace (defaults to kallows)",
                "default": "kallows"
            },
            "repo_slug": {
                "type": "string",
                "description": "Repository slug/name"
            },
            "title": {
                "type": "string",
                "description": "Issue title"
            },
            "content": {
                "type": "string",
                "description": "Issue content/description"
            },
            "kind": {
                "type": "string",
                "description": "Issue type (bug, enhancement, proposal, task)",
                "default": "task"
            },
            "priority": {
                "type": "string",
                "description": "Issue priority (trivial, minor, major, critical, blocker)",
                "default": "minor"
            }
        },
        "required": ["repo_slug", "title", "content"]
    }
),

src/mcp_bitbucket/server.py:703-734 (handler)

The execution handler for bb_create_issue tool within the call_tool dispatcher. Constructs payload and makes POST request to Bitbucket issues API.

elif name == "bb_create_issue":
    workspace = arguments.get("workspace", "kallows")
    repo_slug = arguments.get("repo_slug")
    title = arguments.get("title")
    content = arguments.get("content")
    kind = arguments.get("kind", "task")
    priority = arguments.get("priority", "minor")

    url = f"https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/issues"
    
    payload = {
        "title": title,
        "content": {"raw": content},
        "kind": kind,
        "priority": priority
    }

    response = requests.post(url, json=payload, auth=auth, headers=headers)

    if response.status_code in (200, 201):
        issue_id = response.json().get('id')
        issue_url = response.json().get('links', {}).get('html', {}).get('href', '')
        return [types.TextContent(
            type="text",
            text=f"Issue created successfully\nID: {issue_id}\nURL: {issue_url}"
        )]
    else:
        return [types.TextContent(
            type="text",
            text=f"Failed to create issue: {response.status_code}\n{format_permission_error(response.text)}",
            isError=True
        )]

src/mcp_bitbucket/server.py:46-397 (registration)

The list_tools handler where bb_create_issue is registered by being included in the returned list of tools.

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    """List available tools for Bitbucket integration."""
    return [
        # types.Tool(
        #     name="bb_create_repository",
        #     description="Create a new repository in Bitbucket",
        #     inputSchema={
        #         "type": "object",
        #         "properties": {
        #             "project_key": {
        #                 "type": "string",
        #                 "description": "The project key where the repository will be created (optional for personal repos)"
        #             },
        #             "name": {
        #                 "type": "string",
        #                 "description": "Repository name"
        #             },
        #             "description": {
        #                 "type": "string",
        #                 "description": "Repository description"
        #             },
        #             "is_private": {
        #                 "type": "boolean",
        #                 "description": "Whether the repository should be private",
        #                 "default": True
        #             },
        #             "workspace": {
        #                 "type": "string",
        #                 "description": "Target workspace (defaults to kallows, can use ~ for personal workspace)",
        #                 "default": "kallows"
        #             }
        #         },
        #         "required": ["name"]
        #     }
        # ),



        types.Tool(
            name="bb_create_repository",
            description="Create a new repository in Bitbucket",
            inputSchema={
                "type": "object",
                "properties": {
                    "project_key": {
                        "type": "string",
                        "description": "The project key where the repository will be created (optional for personal repos)"
                    },
                    "name": {
                        "type": "string",
                        "description": "Repository name"
                    },
                    "description": {
                        "type": "string",
                        "description": "Repository description"
                    },
                    "is_private": {
                        "type": "boolean",
                        "description": "Whether the repository should be private",
                        "default": True
                    },
                    "has_issues": {
                        "type": "boolean",
                        "description": "Whether to initialize the repository with issue tracking enabled",
                        "default": True
                    },
                    "workspace": {
                        "type": "string",
                        "description": "Target workspace (defaults to kallows, can use ~ for personal workspace)",
                        "default": "kallows"
                    }
                },
                "required": ["name"]
            }
        ),
        types.Tool(
            name="bb_create_branch",
            description="Create a new branch in a Bitbucket repository",
            inputSchema={
                "type": "object", 
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "branch": {
                        "type": "string",
                        "description": "Name for the new branch"
                    },
                    "start_point": {
                        "type": "string", 
                        "description": "Branch/commit to create from (defaults to main)",
                        "default": "main"
                    }
                },
                "required": ["repo_slug", "branch"]
            }
        ),        
        types.Tool(
            name="bb_delete_repository",
            description="Delete a repository from Bitbucket", # TODO: only works with delete repo priv, see if app password can get delete repo privilege
            inputSchema={
                "type": "object",
                "properties": {
                    "repo_slug": {
                        "type": "string",
                        "description": "The repository slug to delete"
                    },
                    "workspace": {
                        "type": "string",
                        "description": "Target workspace (defaults to kallows, can use ~ for personal workspace)",
                        "default": "kallows"
                    }
                },
                "required": ["repo_slug"]
            }
        ),
        types.Tool(
            name="bb_read_file",
            description="Read a file from a Bitbucket repository",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "path": {
                        "type": "string",
                        "description": "Path to the file in the repository"
                    },
                    "branch": {
                        "type": "string",
                        "description": "Branch name (defaults to main/master)",
                        "default": "main"
                    }
                },
                "required": ["repo_slug", "path"]
            }
        ),
        types.Tool(
            name="bb_write_file",
            description="Write/update a file in a Bitbucket repository",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "path": {
                        "type": "string",
                        "description": "Path where to create/update the file"
                    },
                    "content": {
                        "type": "string",
                        "description": "Content to write to the file"
                    },
                    "message": {
                        "type": "string",
                        "description": "Commit message",
                        "default": "Update file via MCP"
                    },
                    "branch": {
                        "type": "string",
                        "description": "Branch name (defaults to main/master)",
                        "default": "main"
                    }
                },
                "required": ["repo_slug", "path", "content"]
            }
        ),
        types.Tool(
            name="bb_create_issue",
            description="Create an issue in a Bitbucket repository",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "title": {
                        "type": "string",
                        "description": "Issue title"
                    },
                    "content": {
                        "type": "string",
                        "description": "Issue content/description"
                    },
                    "kind": {
                        "type": "string",
                        "description": "Issue type (bug, enhancement, proposal, task)",
                        "default": "task"
                    },
                    "priority": {
                        "type": "string",
                        "description": "Issue priority (trivial, minor, major, critical, blocker)",
                        "default": "minor"
                    }
                },
                "required": ["repo_slug", "title", "content"]
            }
        ),
        types.Tool(
            name="bb_delete_issue",
            description="Delete an issue from a Bitbucket repository",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "issue_id": {
                        "type": "string",
                        "description": "ID of the issue to delete"
                    }
                },
                "required": ["repo_slug", "issue_id"]
            }
        ),
        types.Tool(
            name="bb_search_repositories",
            description="Search repositories in Bitbucket using Bitbucket's query syntax. Search by name (name ~ \"pattern\"), project key (project.key = \"PROJ\"), language (language = \"python\"), or dates (updated_on >= \"2024-01-19\"). NOTE: All dates must be in ISO 8601 format (YYYY-MM-DD). For searching files within repositories, use Bitbucket's code search in the web interface.",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Workspace to search in (defaults to kallows)",
                        "default": "kallows"
                    },
                    "query": {
                        "type": "string",
                        "description": "Search query (e.g., 'name ~ \"test\"' or 'project.key = \"PROJ\"')"
                    },
                    "page": {
                        "type": "integer",
                        "description": "Page number for pagination",
                        "default": 1
                    },
                    "pagelen": {
                        "type": "integer",
                        "description": "Number of results per page (max 100)",
                        "default": 10
                    }
                },
                "required": ["query"]
            }
        ),
        types.Tool(
            name="bb_delete_file",
            description="Delete a file from a Bitbucket repository",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "path": {
                        "type": "string",
                        "description": "Path to the file to delete"
                    },
                    "message": {
                        "type": "string",
                        "description": "Commit message for the deletion",
                        "default": "Delete file via MCP"
                    },
                    "branch": {
                        "type": "string",
                        "description": "Branch name (defaults to main/master)",
                        "default": "main"
                    }
                },
                "required": ["repo_slug", "path"]
            }
        ),
        types.Tool(
            name="bb_create_pull_request",
            description="Create a new pull request in a Bitbucket repository",
            inputSchema={
                "type": "object",
                "properties": {
                    "workspace": {
                        "type": "string",
                        "description": "Repository workspace (defaults to kallows)",
                        "default": "kallows"
                    },
                    "repo_slug": {
                        "type": "string",
                        "description": "Repository slug/name"
                    },
                    "title": {
                        "type": "string",
                        "description": "Pull request title"
                    },
                    "description": {
                        "type": "string",
                        "description": "Pull request description"
                    },
                    "source_branch": {
                        "type": "string",
                        "description": "Branch containing your changes"
                    },
                    "destination_branch": {
                        "type": "string",
                        "description": "Branch you want to merge into",
                        "default": "main"
                    },
                    "close_source_branch": {
                        "type": "boolean",
                        "description": "Close source branch after merge",
                        "default": True
                    }
                },
                "required": ["repo_slug", "title", "source_branch"]
            }
        )                
    ]

Tool Definition Quality

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Create') but doesn't describe what happens upon execution—such as whether it requires specific permissions, returns an issue ID, triggers notifications, or has rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It directly states the tool's function, earning its place with zero waste, making it highly concise and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a creation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., permissions, response format), usage context, and how it fits with siblings. While the schema covers parameters well, the overall context for effective tool selection and invocation is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, clearly documenting all 6 parameters with their types, defaults, and purposes (e.g., 'Issue content/description', 'Issue type'). The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without compensating value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Create') and resource ('issue in a Bitbucket repository'), making the purpose immediately understandable. It distinguishes from siblings like bb_create_branch or bb_create_pull_request by specifying the resource type (issue). However, it doesn't explicitly differentiate from bb_delete_issue or other issue-related tools beyond the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing repository access), exclusions (e.g., not for updating existing issues), or comparisons with siblings like bb_create_pull_request for code changes or bb_delete_issue for removal. Usage is implied by the verb 'Create' but lacks explicit context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Related Tools

bb_create_repositoryC
@Kallows/mcp-bitbucket
create_issue
@PhialsBasement/mcp-github-server-plus
create_issue
@MissionSquad/mcp-github
create-issue
@alsonwangkhem/github-mcp-2
create_issue
@kaiyuanxiaobing/atomgit-mcp-server
create_issueC
@normal-coder/gitee-mcp-server

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Kallows/mcp-bitbucket'

If you have feedback or need assistance with the MCP directory API, please join our Discord server