forgejo-mcp

A Model Context Protocol server that gives AI clients tools to work with a Forgejo or Gitea instance over its REST API: repositories, issues, comments, files, pull requests, and CI status.

It speaks MCP over stdio and calls the Forgejo/Gitea REST API with fetch. The whole server bundles to a single dist/index.js with no runtime framework.

Security model

Tools are tiered by blast radius. The default surface is reads plus writes whose damage is visible and cheap to undo. There are deliberately no merge, delete, or admin tools in it: merging and deleting live behind an opt-in elevated tier, and user, organisation, permission, secret and token administration is not exposed at all, at any tier. Repository lifecycle — creating and deleting repositories — is the exception: those exist, gated behind the elevated tier rather than permanently excluded. This keeps the server safe for unattended use and caps the blast radius of the API token. Pair it with a least-privilege token (repository R/W, issue R/W, user Read).

A small set of high-blast-radius operations — destroying work, and creating a repository whose visibility the caller chooses — is available behind an opt-in, off-by-default elevated tier. With no elevated environment variables set, the tool surface is byte-identical to the safe default described above.

Tools

| Tool | Kind | Purpose | |------|------|---------| | list_repositories | read | List a user's repositories (default: authenticated user); paginated | | get_repository | read | Repository metadata, including default branch | | list_issues | read | List issues; filter by state, labels, type (default issues), text q, milestones, author, assignee, mention, and date; sortable; paginated | | get_issue | read | A single issue with body, labels, assignees | | create_issue | write | Open an issue (labels by id, assignees) | | list_issue_comments | read | Comments on an issue or PR; paginated | | create_issue_comment | write | Add a comment to an issue or PR | | get_file_content | read | Decoded file content (default branch if no ref) | | list_directory | read | List a directory's entries (root if no path); fails on a file path; paginated | | create_file | write | Create a file from plain-text content (optional new branch) | | delete_file | write | Delete a file; requires the blob sha, commits like any change | | update_file | write | Replace a file's content (sha required — the blob SHA being replaced) | | list_pull_requests | read | List PRs; filter by state, milestone id, label ids, and poster; sortable; paginated | | get_pull_request | read | A single PR with merge state | | get_pull_request_diff | read | Unified diff for a PR as plain text | | get_pull_request_files | read | Files a PR changes, with status and line counts; paginated | | create_pull_request | write | Open a PR from a head branch into a base branch | | get_commit_status | read | Combined CI/commit status for a ref | | list_branches | read | List branches with latest commit and protection status; paginated | | get_branch | read | A single branch by name | | create_branch | write | Create a branch from a source ref (default branch if none) | | list_commits | read | List commits; filter by start ref and path; paginated | | get_commit | read | A single commit by SHA or ref | | list_releases | read | List releases; paginated | | get_release_by_tag | read | A release by tag name rather than numeric id | | get_latest_release | read | The current non-draft, non-prerelease release | | edit_release | write | Edit release notes, name, tag, draft/prerelease flags | | get_release | read | A single release by ID, with notes and draft/prerelease flags | | create_release | write | Create a release for a tag (draft, prerelease, notes) | | list_tags | read | List tags with their target commits; paginated | | get_tag | read | A single tag by name | | create_tag | write | Create a tag on a branch or commit (optionally annotated) | | list_pull_request_reviews | read | Reviews on a PR (approvals, change requests, comments); paginated | | create_pull_request_review | write | Submit a review (APPROVED, REQUEST_CHANGES, or COMMENT), with optional inline comments pinned to a commit_id | | request_pull_request_reviewers | write | Request reviews from users (and org teams) on a PR | | create_commit_status | write | Report a commit status (pending, success, error, failure, warning) | | list_commit_statuses | read | Individual statuses on a ref; paginated | | edit_issue_comment | write | Replace the text of a comment (by comment id) | | delete_issue_comment | write | Delete a comment (by comment id); not recoverable here | | list_milestones | read | Milestones in a repository (id, title, state, issue counts); paginated | | get_milestone | read | One milestone by id, or by exact title | | create_milestone | write | Create a milestone (title, description, due date, state) | | edit_milestone | write | Edit a milestone; only the fields you pass change | | delete_milestone | write | Delete a milestone; issues survive but lose it | | list_labels | read | Labels defined in a repository (id, name, color); paginated | | get_label | read | One label definition by id | | create_label | write | Define a new label (name and colour required) | | edit_label | write | Edit a label definition; renames it everywhere it is used | | add_labels | write | Add labels (by name or id) to an issue or PR; existing labels kept | | remove_label | write | Remove one label (by name or id) from an issue or PR | | add_assignees | write | Assign users to an issue or PR; existing assignees kept | | set_issue_state | write | Close or reopen an issue or PR (state only — edit_issue owns title/body) | | edit_issue | write | Edit the title or body of an issue or PR; only the fields you pass change | | edit_pull_request | write | Edit a PR's title, body, state, assignees, labels, milestone, due date or maintainer-edit flag; the base branch is not editable here |

List results are paginated

Every list_* tool except list_directory returns

{ "total_count": 51, "count": 30, "page": 1, "items": [ … ] }

rather than a bare array. Forgejo serves list endpoints a page at a time and caps the page size regardless of the limit asked for, so a bare array cannot be told apart from the first slice of a much longer list. When count is short of total_count, ask for the next page. total_count is omitted when the server does not report one.

list_directory is excluded because its endpoint answers with a single object, not a list, when the path names a file.

Configuration

Supply the target and token at runtime via environment variables:

• FORGEJO_BASE_URL — e.g. https://git.example.com
• FORGEJO_TOKEN — a Forgejo/Gitea API token

Never hardcode the token; inject it from a secret store at launch.

Claude Code

Two setups, both good — pick by whether you value portability or keeping the token out of Claude's config file.

Option A — npx (recommended)

Once the package is on npm, no local checkout or build is needed:

claude mcp add forgejo \
  --env FORGEJO_BASE_URL=https://git.example.com \
  --env FORGEJO_TOKEN=... \
  -- npx -y @rubicontv/forgejo-mcp

Portable and self-updating. Note this stores the token in Claude Code's config (~/.claude.json). If you would rather the token never touch that file, use Option B.

Option B — local wrapper (keeps the token out of config)

A small launcher sources a chmod 600 env file at startup, so the token lives only in that file (ideally hydrated from a secret manager) and never in ~/.claude.json:

#!/bin/sh
# ~/.config/forgejo-mcp/launch.sh
set -eu
. "$HOME/.config/forgejo-mcp/forgejo-mcp.env"   # sets FORGEJO_BASE_URL, FORGEJO_TOKEN
export FORGEJO_BASE_URL FORGEJO_TOKEN
exec npx -y @rubicontv/forgejo-mcp                # or: exec node /path/to/forgejo-mcp/dist/index.js

Point Claude Code at the wrapper — no env block, so no secret in the config:

{
  "mcpServers": {
    "forgejo": {
      "command": "/Users/you/.config/forgejo-mcp/launch.sh"
    }
  }
}

Running from a local build (no npm)

If you are working from a checkout instead of the published package:

{
  "mcpServers": {
    "forgejo": {
      "command": "node",
      "args": ["/path/to/forgejo-mcp/dist/index.js"],
      "env": {
        "FORGEJO_BASE_URL": "https://git.example.com",
        "FORGEJO_TOKEN": "..."
      }
    }
  }
}

Allowlisting

To let an agent use the server without a prompt on every call, allowlist it. On the safe default surface (no elevated tier), blanket-allowlisting the whole server is fine:

mcp__forgejo

If you turn on the elevated tier, do not do this — a blanket allowlist would let every elevated tool run without a prompt: merge_pull_request, delete_branch, delete_repo, delete_label, delete_release and delete_tag. Allowlist named default tools only, never an elevated one, and never delete_repo under any circumstances — its confirm argument catches a malformed call, not a misled one. For example:

mcp__forgejo__create_issue
mcp__forgejo__create_pull_request

See the allowlist warning in the Elevated tier section below.

Elevated tier (opt-in, off by default)

The server can optionally expose a minimal set of high-blast-radius tools: operations that destroy work in ways this server cannot undo. This tier is off by default and must be deliberately enabled by the operator.

| Tool | Kind | Operation | |------|------|-----------| | merge_pull_request | elevated | Merge a PR (merge / rebase / squash) into its base branch, pinned to a required head_commit_id; pass delete_branch_after_merge to clean up the head branch | | delete_branch | elevated | Permanently delete a branch | | delete_repo | elevated | Permanently delete a repository; confirm must equal owner/repo | | delete_label | elevated | Permanently delete a label definition, stripping it from every issue and pull request that carried it | | delete_release | elevated | Permanently delete a release; its notes and uploaded assets do not exist in git | | delete_tag | elevated | Permanently delete a tag; if its commits are unreachable from any branch, deleting it orphans them |

Every elevated tool is prefixed [ELEVATED — DESTRUCTIVE] and carries destructiveHint: true. The tier holds nothing else: a tool that does not destroy something this server cannot restore belongs in the default surface.

delete_repo requires confirm to equal owner/repo exactly. Be clear about what that buys: it catches a malformed or half-specified call, and nothing more. Both confirm and the target come from the same tool-call arguments, so text injected into an issue can satisfy it as easily as a careful caller. Deleting a repository is the only operation here with no undo of any kind, so never allowlist delete_repo — the per-call approval prompt is the actual guard.

merge_pull_request requires head_commit_id — the head SHA from get_pull_request. Forgejo refuses the merge if the branch has moved since that SHA, so commits pushed after the review cannot be swept in. Be precise about what that is: a freshness guard, not proof of provenance. Nothing verifies the SHA came from reading the pull request, so it constrains what gets merged, not whether anyone looked. The per-call approval prompt is what covers the latter.

Why it is gated so carefully

This server hands tools to an LLM that reads untrusted content — issue bodies, PR text, file contents. That is a prompt-injection surface: a misled agent should never be able to merge or delete anything. So the elevated tier is double-gated and uses a separate token.

Enabling it — the double gate

Elevated tools are registered only when all three of these hold:

• FORGEJO_MCP_ELEVATED=1 — an explicit opt-in flag, and
• FORGEJO_MCP_ELEVATED_TOKEN — a token distinct from FORGEJO_TOKEN. This is checked, not merely asked for: if the two are identical the tier stays off and the server logs why. A second token that equals the first is not a second token.
• FORGEJO_TOKEN must itself be set. Elevation is additive on top of the default surface, so without it the tier stays off rather than leaving the destructive tools as the only ones that work.

The default FORGEJO_TOKEN never performs an elevated operation — elevated calls use FORGEJO_MCP_ELEVATED_TOKEN exclusively. Scope that token to only the repositories and permissions the destructive tools actually need.

If FORGEJO_MCP_ELEVATED=1 is set but FORGEJO_MCP_ELEVATED_TOKEN is missing, the server fails closed: the elevated tools are not registered and a warning is logged to stderr.

{
  "mcpServers": {
    "forgejo": {
      "command": "node",
      "args": ["/path/to/forgejo-mcp/dist/index.js"],
      "env": {
        "FORGEJO_BASE_URL": "https://git.example.com",
        "FORGEJO_TOKEN": "…read/write token…",
        "FORGEJO_MCP_ELEVATED": "1",
        "FORGEJO_MCP_ELEVATED_TOKEN": "…distinct, narrowly-scoped token…"
      }
    }
  }
}

⚠️ Allowlist warning — read before enabling

This MCP is commonly whole-server allowlisted (e.g. mcp__forgejo) so an agent can use it autonomously without per-call prompts. If you enable the elevated tier under a blanket allowlist, the destructive tools also run without any prompt. A single prompt-injection payload in an issue or PR could then merge or delete on your behalf.

Therefore, when the elevated tier is on:

• Do NOT blanket-allow the whole server (mcp__forgejo).
• Allowlist only the specific safe tools you want to run autonomously (e.g. mcp__forgejo__create_issue), and leave every elevated tool — merge_pull_request, delete_branch, delete_repo, delete_label, delete_release and delete_tag — prompting on every call. delete_repo should never be allowlisted at all: its confirm argument catches a malformed call, not a misled one.

The server cannot enforce the client's allowlist — distinct tool naming and this warning are the mitigation. Enabling elevated tools is a decision the operator owns.

Permanently excluded

The elevated tier is intentionally tiny. The following are never exposed, regardless of any flag: user management, secret/variable writes, permission or collaborator changes, and org/repo admin. Those are not appropriate to hand to an LLM that reads untrusted content, so they stay out by design. Adding any destructive tool requires explicit owner sign-off and a matching token-scope review.

Build and test

npm install
npm run build     # esbuild -> dist/index.js
npm run smoke     # builds, then runs a token-free MCP handshake + tools/list
npm run typecheck # tsc --noEmit

Contributors

See CONTRIBUTING.md to get started, the Code of Conduct for community expectations, and SECURITY.md to report a vulnerability privately.

License and attribution

Licensed under the Apache License 2.0. This is an independent, clean-room implementation; see NOTICE. It was inspired by nsvk13/forgejo-mcp-server, with thanks, but shares no source code with it.