# gitopia/gitopia-mcp-server [Health: Active]

**Category:** 🔄 Version Control  
**Repository:** https://github.com/gitopia/gitopia-mcp-server  
**GitHub Stars:** 3  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gitopia-gitopia-mcp-server

## Description
Decentralized Git with on-chain governance, bounties, and DAOs. Tools for repos, issues, PRs, labels, releases, bounties, and DAO proposals. Auto-wallet on first use, trust tiers, and approval mode for human-in-the-loop. Go binary or Docker.

## Tools
Capabilities this server exposes over MCP:

- **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
- **create_user** — Create on-chain Gitopia user for wallet
- **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
- **list_tags** — List version tags
- **list_commits** — Browse commit history for a branch
- **list_releases** — List published releases
- **create_release** — Publish a new release
- **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
- **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_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
- **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
- **list_labels** — List repository labels
- **create_label** — Create label (on-chain)
- **delete_label** — Delete label (on-chain)
- **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
- **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_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

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "gitopia-mcp-server": {
    "command": "npx",
    "args": ["-y","gitopia-gitopia-mcp-server"],
    "env": {
      "GITOPIA_MNEMONIC": "",
      "MCP_WORKSPACE_PATH": ""
    }
  }
}
```

**Requires environment variables:** `GITOPIA_MNEMONIC`, `MCP_WORKSPACE_PATH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# Gitopia MCP Server

MCP server for [Gitopia](https://gitopia.com) — 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)

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

Then add the config for your editor (see [Editor Setup](#editor-setup) below).

### Native Binary

Download from [GitHub Releases](https://github.com/gitopia/gitopia-mcp-server/releases), or:

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

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

## Editor Setup

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

```bash
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`:

```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](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/docs/installation-guides/codex.md)

</details>

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

Add to your project's `.mcp.json`:

```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](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/docs/installation-guides/claude-code.md)

</details>

<details>
<summary><strong>Cursor</strong></summary>

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

```json
{
  "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](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/docs/installation-guides/cursor.md)

</details>

<details>
<summary><strong>VS Code</strong></summary>

[Full VS Code guide](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/docs/installation-guides/vscode.md)

</details>

<details>
<summary><strong>Windsurf</strong></summary>

[Full Windsurf guide](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/docs/installation-guides/windsurf.md)

</details>

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

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

```json
{
  "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](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/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](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/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

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

See [CONTRIBUTING.md](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/CONTRIBUTING.md) for development guidelines.

## License

[MIT](https://github.com/gitopia/gitopia-mcp-server/blob/HEAD/LICENSE)