Gitza MCP server for Claude Code and other MCP clients, with local stdio and hosted OAuth transports. MIT licensed.
  • TypeScript 95.6%
  • JavaScript 3.4%
  • Dockerfile 0.7%
  • Shell 0.3%
Find a file
2026-10-26 00:43:58 +02:00
.forgejo/workflows Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
deploy Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
migrations Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
src Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
tests Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
.dockerignore Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
.env.example Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
.gitignore Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
.nvmrc Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
.prettierignore Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
.prettierrc.json Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
compose.yml Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
CONTRIBUTING.md Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
Dockerfile Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
eslint.config.mjs Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
LICENSE Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
OPERATIONS.md docs: record published archive and production build settings 2026-10-25 21:15:44 +02:00
package.json Prepare MCP 0.1.0 production deployment and Claude hosted login 2026-10-25 20:58:49 +02:00
playwright.config.ts Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
pnpm-lock.yaml Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
README.md docs: publish npm installation instructions 2026-10-26 00:43:58 +02:00
RELEASE.md docs: publish npm installation instructions 2026-10-26 00:43:58 +02:00
THIRD-PARTY-NOTICES.md Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
tsconfig.build.json Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
tsconfig.json Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
vitest.config.ts Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00
vitest.integration.config.ts Initial standalone Gitza MCP implementation 2026-10-25 19:56:48 +02:00

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.