Gitopia MCP Server

MCP server for Gitopia — decentralized Git with on-chain governance, bounties, and DAO management. Works with Cursor, VS Code, Claude Code, Claude Desktop, Windsurf, and any MCP-compatible tool.

57 tools | 3 prompts | 4 resource templates

Zero-config start: a wallet is auto-generated on first use. No setup beyond pasting a config snippet.

Quick Start

Docker (Recommended)

docker pull ghcr.io/gitopia/gitopia-mcp-server:latest

Then add the config for your editor (see Editor Setup below).

Native Binary

Download from GitHub Releases, or:

go install github.com/gitopia/gitopia-mcp-server/cmd/server@latest

Requires Go 1.25+ and git-remote-gitopia (curl https://get.gitopia.com | bash).

Editor Setup

<details> <summary>OpenAI Codex</summary>

codex mcp add gitopia -- docker run --rm -i --platform linux/amd64 \
  -v "${HOME}/.mcp/gitopia:/home/mcp/.mcp/gitopia" \
  -e MCP_WORKSPACE_PATH=/home/mcp/.mcp/gitopia/workspace \
  ghcr.io/gitopia/gitopia-mcp-server:latest stdio

Or add to ~/.codex/config.toml:

[mcp_servers.gitopia]
command = "docker"
args = [
  "run", "--rm", "-i", "--platform", "linux/amd64",
  "-v", "${HOME}/.mcp/gitopia:/home/mcp/.mcp/gitopia",
  "-e", "MCP_WORKSPACE_PATH=/home/mcp/.mcp/gitopia/workspace",
  "ghcr.io/gitopia/gitopia-mcp-server:latest", "stdio"
]

Full Codex guide

</details>

<details> <summary>Claude Code</summary>

Add to your project's .mcp.json:

{
  "mcpServers": {
    "gitopia": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--platform", "linux/amd64",
        "-v", "${HOME}/.mcp/gitopia:/home/mcp/.mcp/gitopia",
        "-v", "${PWD}:/workspace", "-w", "/workspace",
        "-e", "MCP_WORKSPACE_PATH=/workspace",
        "ghcr.io/gitopia/gitopia-mcp-server:latest", "stdio"
      ],
      "env": {}
    }
  }
}

Full Claude Code guide

</details>

<details> <summary>Cursor</summary>

Add to ~/.cursor/mcp.json (macOS) or %APPDATA%\Cursor\mcp.json (Windows):

{
  "mcpServers": {
    "gitopia": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--platform", "linux/amd64",
        "-v", "${HOME}/.mcp/gitopia:/home/mcp/.mcp/gitopia",
        "-v", "${workspaceFolder}:/workspace", "-w", "/workspace",
        "-e", "MCP_WORKSPACE_PATH=/workspace",
        "ghcr.io/gitopia/gitopia-mcp-server:latest", "stdio"
      ],
      "env": {}
    }
  }
}

Full Cursor guide

</details>

Full VS Code guide

</details>

<details> <summary>Windsurf</summary>

Full Windsurf guide

</details>

<details> <summary>Claude Desktop</summary>

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "gitopia": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--platform", "linux/amd64",
        "-v", "${HOME}/.mcp/gitopia:/home/mcp/.mcp/gitopia",
        "-e", "MCP_WORKSPACE_PATH=/home/mcp/.mcp/gitopia/workspace",
        "ghcr.io/gitopia/gitopia-mcp-server:latest", "stdio"
      ],
      "env": {}
    }
  }
}

</details>

Using an existing wallet? Set GITOPIA_MNEMONIC in your shell, then add "-e", "GITOPIA_MNEMONIC" to the Docker args. Never hardcode mnemonics in config files.

Tools (57)

Context Management (4)

| Tool | Description | |------|-------------| | get_user_context | Get current identity, address, and available DAOs | | set_active_dao | Switch operations to a DAO context | | refresh_user_context | Reload user info from chain | | claim_fee_grant | Claim fee grant from faucet |

User Management (1)

| Tool | Description | |------|-------------| | create_user | Create on-chain Gitopia user for wallet |

Repository Management (7)

| Tool | Description | |------|-------------| | list_repos | List repositories for owner | | create_repo | Create remote repository | | get_repo | Get repository details | | list_branches | List branches | | get_file_contents | Read file without cloning | | fork_repository | Fork a repository | | toggle_repository_forking | Enable/disable forking |

Tags, Commits, Releases (4)

| Tool | Description | |------|-------------| | list_tags | List version tags | | list_commits | Browse commit history for a branch | | list_releases | List published releases | | create_release | Publish a new release |

Issue Management (5)

| Tool | Description | |------|-------------| | list_issues | List issues | | get_issue | Get full issue details | | create_issue | Create issue (on-chain) | | comment_on_issue | Comment on issue (on-chain) | | update_issue | Update state, labels, assignees |

Pull Request Management (6)

| Tool | Description | |------|-------------| | list_pull_requests | List PRs | | get_pull_request | Get full PR details | | get_pull_request_diff | Get unified diff for a PR | | create_pull_request | Create PR (on-chain) | | comment_on_pull_request | Comment on PR (general or inline) | | merge_pull_request | Merge PR (on-chain) |

Git Operations (5)

| Tool | Description | |------|-------------| | git_clone | Clone repository to workspace | | git_push | Push commits to remote | | create_feature_branch | Create and checkout new branch | | sync_with_remote | Fetch and merge/rebase | | commit_and_push_changes | Stage + commit + push in one step |

Workflow Orchestration (3)

| Tool | Description | |------|-------------| | bootstrap_repo | Create remote + local init + files + push | | create_feature_branch_pr | Branch + changes + commit + push + PR | | update_feature_branch | Add commits to existing branch/PR |

Label Management (3)

| Tool | Description | |------|-------------| | list_labels | List repository labels | | create_label | Create label (on-chain) | | delete_label | Delete label (on-chain) |

DAO & Governance (9)

| Tool | Description | |------|-------------| | get_dao | Get DAO details including group_id and group_policy_address | | create_dao | Create DAO with members and voting | | dao_list_members | List DAO members and weights | | dao_list_proposals | List governance proposals | | dao_get_proposal | Get proposal details with tally | | dao_update_members | Add/remove/change member weights | | dao_submit_proposal | Create governance proposal | | dao_vote | Vote on proposal | | dao_exec | Execute passed proposal |

Bounty Management (6)

| Tool | Description | |------|-------------| | list_bounties | Discover bounties | | get_bounty | Get bounty details | | create_bounty | Attach crypto reward to issue | | update_bounty | Modify bounty expiry | | close_bounty | Deactivate bounty | | delete_bounty | Permanently remove bounty |

Batch & Approval (4)

| Tool | Description | |------|-------------| | batch_execute | Execute up to 10 ops in one transaction | | confirm_transaction | Broadcast pending transaction | | reject_transaction | Cancel pending transaction | | list_pending_transactions | List pending transactions |

Prompts

| Prompt | Description | |--------|-------------| | fix-issue | Complete workflow: clone, branch, fix, test, PR | | review-pr | Review a pull request: inspect, comment, approve | | hunt-bounty | Discover bounties, evaluate, claim, fix, submit |

Security

Trust tiers gate tool access: readonly < localwrite < chainwrite
Rate limiting on chain-write operations (default 10/min, 100/hr)
Message allowlist only signs /gitopia.gitopia.gitopia. and /cosmos.group.v1.
Workspace isolation blocks path traversal attacks
Approval mode holds transactions for explicit confirmation before broadcast
Non-root Docker containers run as unprivileged user

See SECURITY.md for vulnerability reporting.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | GITOPIA_MNEMONIC | auto-generated | BIP-39 wallet mnemonic | | GITOPIA_GRPC_ENDPOINTS | gitopia-grpc.polkachu.com:11390 | gRPC endpoints | | TRUST_LEVEL | chainwrite | readonly, localwrite, chainwrite | | TOOLSETS | all | Comma-separated toolsets to enable (see below) | | DRY_RUN | false | Preview transactions without broadcasting | | APPROVAL_MODE | false | Require confirmation before chain writes | | MCP_WORKSPACE_PATH | ~/.mcp/gitopia/workspace | Workspace root | | MCP_LOG_LEVEL | info | Log level | | TRANSPORT | stdio | stdio or http | | PORT | 8080 | HTTP listen port (when TRANSPORT=http) |

See env.example for the full list.

Toolsets

Control which tools are exposed to the MCP client. Useful for reducing context window usage in AI assistants.

| Toolset | Tools | Description | |---------|-------|-------------| | core | 52 | All tools except workflow orchestrators (always included) | | workflow | 5 | bootstrap_repo, create_feature_branch, create_feature_branch_pr, update_feature_branch, commit_and_push_changes |

TOOLSETS=all (default): All 57 tools
TOOLSETS=core: 52 tools (hides workflow orchestrators)
TOOLSETS=core,workflow: Same as all

For Claude Code users, TOOLSETS=core is recommended since Claude can orchestrate git operations natively.

Development

go build ./cmd/server          # build
go test ./...                  # test
go vet ./...                   # lint
docker build -t gitopia-mcp-server:latest .  # docker

See CONTRIBUTING.md for development guidelines.

License

MIT

gitopia-mcp-server