= poly-git-mcp

image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://img.shields.io/badge/Philosophy-Palimpsest-purple.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-licence"]

:toc: :toc-placement!:

image:https://img.shields.io/badge/RSR-compliant-gold[RSR Compliant,link=https://github.com/hyperpolymath/rhodium-standard-repositories] image:https://img.shields.io/badge/MCP-server-blue[MCP Server,link=https://github.com/modelcontextprotocol]

Unified MCP server for Git forge management. Provides Model Context Protocol tools for interacting with GitHub, GitLab, Gitea, and Bitbucket through their respective CLI tools and APIs.

toc::[]

== Overview

poly-git-mcp exposes Git forge capabilities through the Model Context Protocol (MCP), enabling AI assistants and other MCP clients to manage repositories, issues, pull requests, and CI/CD across multiple Git platforms.

== Adapters

=== GitHub (13 tools) GitHub via gh CLI:

• gh_repo_list - List repositories
• gh_repo_view - View repository details
• gh_repo_clone - Clone a repository
• gh_issue_list - List issues
• gh_issue_view - View an issue
• gh_issue_create - Create an issue
• gh_pr_list - List pull requests
• gh_pr_view - View a pull request
• gh_pr_create - Create a pull request
• gh_pr_merge - Merge a pull request
• gh_release_list - List releases
• gh_workflow_list - List workflow runs
• gh_auth_status - Check authentication status

=== GitLab (12 tools) GitLab via glab CLI:

• glab_project_list - List projects
• glab_project_view - View project details
• glab_issue_list - List issues
• glab_issue_view - View an issue
• glab_issue_create - Create an issue
• glab_mr_list - List merge requests
• glab_mr_view - View a merge request
• glab_mr_create - Create a merge request
• glab_mr_merge - Merge a merge request
• glab_pipeline_list - List pipelines
• glab_ci_status - Show CI/CD status
• glab_auth_status - Check authentication status

=== Gitea (11 tools) Gitea/Forgejo via tea CLI:

• tea_repo_list - List repositories
• tea_repo_view - View repository details
• tea_issue_list - List issues
• tea_issue_view - View an issue
• tea_issue_create - Create an issue
• tea_pr_list - List pull requests
• tea_pr_view - View a pull request
• tea_pr_create - Create a pull request
• tea_release_list - List releases
• tea_org_list - List organizations
• tea_login_list - List configured logins

=== Bitbucket (10 tools) Bitbucket via REST API:

• bb_repo_list - List repositories
• bb_repo_view - View repository details
• bb_issue_list - List issues
• bb_pr_list - List pull requests
• bb_pr_view - View a pull request
• bb_pipeline_list - List pipelines
• bb_branches - List branches
• bb_commits - List commits
• bb_workspaces - List workspaces
• bb_user - Get current user info

== Runtime Mode

[IMPORTANT]

Local-Agent Mode Only — This MCP server wraps CLI tools (gh, glab, tea) and uses REST APIs (Bitbucket). It requires --allow-run and --allow-net permissions. It cannot run in Hosted-HTTP mode due to CLI dependencies.

|=== |Mode |Supported |Notes

|Local-Agent (stdio) |✓ Yes |Primary mode. Runs locally, executes CLI commands.

|Hosted-HTTP |✗ No |Cannot wrap CLI tools from a hosted environment. |===

== Security Boundary

[WARNING]

This MCP server executes external CLI commands using Deno's --allow-run permission and makes API calls with --allow-net. The security boundary is your local Git forge authentication.

What this means:

• GitHub: Uses gh auth login session or GITHUB_TOKEN
• GitLab: Uses glab auth login session or GITLAB_TOKEN
• Gitea: Uses tea login configuration
• Bitbucket: Uses BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD
• The MCP client (e.g., Claude) can perform any action your credentials allow

Recommendations:

1. Use tokens with minimal necessary scopes
2. Consider separate tokens for MCP access
3. Avoid tokens with delete or admin permissions
4. Review tool calls before approving in your MCP client
5. For Bitbucket, create a dedicated app password with limited scope

== Requirements

• https://deno.land/[Deno] runtime (v2.0+)
• https://cli.github.com/[GitHub CLI (gh)] (optional, for GitHub tools)
• https://gitlab.com/gitlab-org/cli[GitLab CLI (glab)] (optional, for GitLab tools)
• https://gitea.com/gitea/tea[tea] (optional, for Gitea tools)
• Bitbucket app password (optional, for Bitbucket tools)

== Configuration

=== Bitbucket Authentication

Set environment variables for Bitbucket API access:

[source,bash]

export BITBUCKET_USERNAME=your-username export BITBUCKET_APP_PASSWORD=your-app-password

Create an app password at: https://bitbucket.org/account/settings/app-passwords/

== Installation

[source,bash]

git clone https://github.com/hyperpolymath/poly-git-mcp cd poly-git-mcp

== Usage

Run as MCP server (Local-Agent mode):

[source,bash]

deno run --allow-run --allow-read --allow-env --allow-net main.js

Or use the systemd service:

[source,bash]

systemctl --user enable poly-git-mcp systemctl --user start poly-git-mcp

== Smoke Test

Verify the server is working correctly:

[source,bash]

1. Check Deno can run the server

deno run --allow-run --allow-read --allow-env --allow-net main.js & SERVER_PID=$!

2. Verify at least one CLI is accessible

gh --version || glab --version || tea --version

3. Test authentication (pick your provider)

gh auth status # GitHub glab auth status # GitLab tea login list # Gitea

4. Cleanup

kill $SERVER_PID

Expected smoke test results:

|=== |Check |Expected Result

|Server starts |No errors, listens on stdio

|CLI available |At least one Git CLI returns version

|Auth configured |CLI shows logged-in user

|Tool call works |Returns repos/issues (if any exist) |===

== License

MIT