- TypeScript 95.6%
- JavaScript 3.4%
- Dockerfile 0.7%
- Shell 0.3%
| .forgejo/workflows | ||
| deploy | ||
| migrations | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc.json | ||
| compose.yml | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| eslint.config.mjs | ||
| LICENSE | ||
| OPERATIONS.md | ||
| package.json | ||
| playwright.config.ts | ||
| pnpm-lock.yaml | ||
| README.md | ||
| RELEASE.md | ||
| THIRD-PARTY-NOTICES.md | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| vitest.config.ts | ||
| vitest.integration.config.ts | ||
Gitza MCP
Connect MCP clients to selected Gitza repositories. The same implementation runs locally over stdio or as a hosted service with browser sign-in.
Source: Gitza/gitza-mcp on Gitza.
User guide: AI tools and MCP, including setup, permissions, troubleshooting and client compatibility limits.
Version 0.1.0 requires Node 24 or newer. Install the pinned npm release:
npm install -g @gitza/mcp@0.1.0
The same archive and its SHA-256 checksum are available on the Gitza release page.
Local connection
Create a token in Gitza under Settings → Applications, restricted to the repositories you want to expose. Select read:repository and read:issue for reading, or write:repository and write:issue for the supported writes. Account/admin scopes are not required. A local allowlist also restricts public repositories that the token could otherwise read.
Set GITZA_TOKEN in the environment used to launch your client. Do not place the
token in shell arguments, Git URLs or a committed configuration file. Then add
the installed executable to Claude Code:
claude mcp add --transport stdio --scope user gitza \
--env GITZA_REPOSITORIES=you/project -- gitza-mcp stdio
To build and install from source:
git clone https://git.gitza.co.za/Gitza/gitza-mcp.git
cd gitza-mcp
corepack pnpm install --frozen-lockfile
corepack pnpm build
npm pack --ignore-scripts
npm install -g ./gitza-mcp-0.1.0.tgz
For clients using JSON configuration:
{
"mcpServers": {
"gitza": {
"command": "gitza-mcp",
"args": ["stdio"],
"env": { "GITZA_REPOSITORIES": "you/project", "GITZA_WRITE": "false" }
}
}
}
The client process must inherit GITZA_TOKEN. Use the client's secure secret
configuration if it does not inherit shell variables. Never commit a literal token.
GITZA_REPOSITORIES is a comma-separated, explicit allowlist. Read-only is the
default; set GITZA_WRITE=true to enable the three write tools. Tokens remain
revocable in Gitza regardless of this setting. GITZA_URL selects one fixed
instance; tools cannot change it. Local credentials are never sent to a broker.
Hosted connection
Connect to the Gitza hosted service:
claude mcp add --transport http --scope user gitza https://mcp.gitza.co.za/mcp
claude mcp login gitza
You can also run /mcp in Claude Code and follow browser authentication. Select repositories
and optionally enable issue creation, comments and PR creation. New repositories
are never selected automatically. Visit /connections on the MCP origin to revoke
individual connections or remove all grants and the stored upstream credential.
The OAuth scope gitza:access means access to a user-approved connection. Exact
repositories and read/write capabilities live in the persisted grant and are
checked on every call. OAuth tokens are opaque, bound to the MCP resource and
separate from upstream account credentials.
Tools
| Tool | Main inputs |
|---|---|
list_repositories |
Optional query, page, limit |
get_repository |
repository |
list_directory |
repository, optional path, ref, page, limit |
get_file |
repository, path, optional ref, start_line, max_lines |
list_branches |
repository, optional page, limit |
list_commits |
repository, optional sha, page, limit |
list_issues |
repository, optional state, page, limit |
get_issue |
repository, index |
list_comments |
repository, index, optional page, limit |
list_pull_requests |
repository, optional state, page, limit |
get_pull_request |
repository, index |
get_pull_request_diff |
repository, index, optional line window and expected_head_sha |
create_issue |
repository, title, optional body |
add_comment |
repository, index, body |
create_pull_request |
repository, title, base, head, optional body |
repository is owner/name. PR creation requires an already pushed branch in the
selected repository; fork-qualified heads are rejected. Use
ordinary Git tools for editing, committing and pushing. This release does not
merge, delete repositories, execute code, provide CI tools or forward arbitrary API
requests. Symlinks, submodules and external download URLs are not followed.
Lists return data and next_page. Text readers return windows and next_line.
Pin file reads to a commit SHA and use the PR head SHA when paging a diff. Binary
files are reported explicitly. Results are capped at 256 KiB, text windows at
60,000 bytes, and upstream bodies at 4 MiB. Larger results return an actionable
error. There is no implicit whole-repository download or indexing.
Tool errors use isError with a stable error code. Missing and inaccessible objects
share an error to avoid disclosing private metadata. Writes are never retried
automatically. After an uncertain write outcome, inspect Gitza before retrying.
Data boundaries
Repository content and comments are untrusted data. They cannot grant permissions. Every operation is constrained by the connection's repository IDs, allowed actions and current upstream access. A renamed/replaced repository requires reselection.
The hosted service stores encrypted upstream account credentials. On the supported backend, OAuth credentials can be broader than the repositories selected in MCP; the MCP grant restricts their use by this service. Protect database backups and encryption keys separately. No shared administrator credential is used for tools.
Content returned to your AI client may be processed by its model provider outside South Africa. Local or South African MCP hosting does not determine where that provider processes the response. The MCP itself makes no model calls.
Develop and verify
From the repository root, use Node 24 and the pinned package manager:
corepack pnpm install --frozen-lockfile
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
PLAYWRIGHT_SKIP_BROWSER_GC=1 corepack pnpm exec playwright install chromium
corepack pnpm test:integration
Integration tests require Docker. They create a uniquely named, loopback-only
instance and PostgreSQL database, exercise real API and OAuth flows, then remove
only their own containers and volumes. They never target a deployed service.
MCP_KEEP_FIXTURE=1 retains that disposable stack for debugging; the printed path
contains secret test configuration and must not be committed or shared.
See OPERATIONS.md for hosting, RELEASE.md for release evidence and CONTRIBUTING.md for contribution instructions. MIT applies only to the MCP implementation; see THIRD-PARTY-NOTICES.md.