Forgejo MCP Server

> 📦 This project has moved. Development, issues, releases, and container

> images now live at

> ****.

> The Codeberg repository at `codeberg.org/goern/forgejo-mcp` remains only as a

> read-only mirror, and its container registry no longer publishes images —

> pull from `git.b4mad.industries/agentic-forges/forgejo-mcp` instead. Issue

> numbers are preserved across the move. Contributions from humans and

> AI agents are welcome at the new location.

>

> ```bash

> git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git

> ```

>

> If you have a remote or a bookmark pointing at `forgejo.b4mad.net`, that is

> the same forge under its previous name — renamed 2026-07-29, not moved

> again. The old name still resolves and serves port 2222 with the same host

> key, so existing clones keep working; repoint them at your leisure:

>

> ```bash

> git remote set-url origin \

> ssh://git@git.b4mad.industries:2222/agentic-forges/forgejo-mcp.git

> ssh-keyscan -p 2222 git.b4mad.industries >> ~/.ssh/known_hosts

> ```

Connect your AI assistant to Forgejo repositories. Manage issues, pull requests, files, and more through natural language.

What It Does

Forgejo MCP Server is an integration plugin that connects Forgejo with Model Context Protocol (MCP) systems. Once configured, you can interact with your Forgejo repositories through any MCP-compatible AI assistant like Claude, Cursor, or VS Code extensions.

Example commands you can use:

• "List all my repositories"
• "Create an issue titled 'Bug in login page'"
• "Show me open pull requests in my-org/my-repo"
• "Get the contents of README.md from the main branch"
• "Show me the latest Actions workflow runs in agentic-forges/forgejo-mcp"

Quick Start

1. Install

Option A: Using Go (Recommended)

git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git
cd forgejo-mcp
go install .

Ensure `$GOPATH/bin` (typically `~/go/bin`) is in your PATH.

> Note: `go install` from the module path works from the first release

> after the module was renamed (see Known Issues):

>

> ```bash

> go install git.b4mad.industries/agentic-forges/forgejo-mcp/v2@latest

> ```

Option B: Download Binary

Download the latest release from the releases page.

For Arch Linux, use your favorite AUR helper:

yay -S forgejo-mcp      # builds from source
yay -S forgejo-mcp-bin  # uses pre-built binary

Option C: Nix / NixOS

You can run the server directly using the Nix package manager:

nix-shell -p forgejo-mcp

Or using Flakes:

nix run nixpkgs#forgejo-mcp

> Note: `forgejo-mcp` is currently only available in the `unstable` channel and is not yet part of the 25.11 stable release.

Option D: Container image

A signed multi-stage OCI image is published on every release to

`git.b4mad.industries/agentic-forges/forgejo-mcp`. Run the server without building from source:

# Latest release
podman run --rm -i \
  -e FORGEJO_ACCESS_TOKEN="" \
  git.b4mad.industries/agentic-forges/forgejo-mcp:latest \
  --transport stdio --url https://your-forgejo-instance.org

# Or pin a specific version
podman run --rm -i git.b4mad.industries/agentic-forges/forgejo-mcp:v2.24.0 --help

The image is single-arch (`linux/amd64`), signed with cosign, and carries an

attached CycloneDX SBOM. See Verify the container image

to check the signature and provenance before running.

2. Get Your Access Token

1. Log into your Forgejo instance

2. Go to Settings → Applications → Access Tokens

3. Create a new token with the permissions you need (repo, issue, etc.)

3. Configure Your AI Assistant

Add this to your MCP configuration file:

For stdio mode (most common):

{
  "mcpServers": {
    "forgejo": {
      "command": "forgejo-mcp",
      "args": [
        "--transport", "stdio",
        "--url", "https://your-forgejo-instance.org"
      ],
      "env": {
        "FORGEJO_ACCESS_TOKEN": "",
        "FORGEJO_USER_AGENT": "forgejo-mcp/1.0.0"
      }
    }
  }
}

For streamable HTTP mode (recommended for remote/Claude.ai):

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

When using streamable HTTP mode, start the server first:

forgejo-mcp --transport http --url https://your-forgejo-instance.org --token

Multi-tenant HTTP mode (optional):

You can run a single centralized `forgejo-mcp` instance and let each client provide its own token via the standard HTTP `Authorization` header. This enables serving multiple users or agents from one server.

1. Start the server (optionally without any global token):

forgejo-mcp --transport http --url https://your-forgejo-instance.org

2. Clients include their specific token in each request:

See demos/multi-tenant-http.md for a copy-pasteable walkthrough.

> Design rationale, token-resolution rules, and request-isolation guarantees: see the `stateless-http-auth` OpenSpec change (`openspec/changes/archive/`).

For SSE mode (legacy HTTP-based):

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/sse"
    }
  }
}

When using SSE mode, start the server first:

forgejo-mcp --transport sse --url https://your-forgejo-instance.org --token

4. Start Using It

Open your MCP-compatible AI assistant and try:

List all my repositories

Available Tools

Command-line arguments take priority over environment variables.

Uploading attachments from the host filesystem

`create_issue_attachment`, `create_comment_attachment`, and

`create_release_attachment` accept either base64 `content` or a `file_path` on

the machine running `forgejo-mcp`. The path form avoids base64-expanding a large

release artifact through the MCP transport.

It is off by default, because it hands whatever drives the MCP client the

ability to read any file the server process can read — a prompt-injected agent

could upload `~/.ssh/id_ed25519` as a public release asset. Turn it on

deliberately, and prefer confining it:

export FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD=1
export FORGEJO_MCP_UPLOAD_ROOT=/home/you/build/dist   # optional but recommended

With `FORGEJO_MCP_UPLOAD_ROOT` set, a path that resolves outside that directory

— by being absolute, by `..`, or through a symlink — is rejected before anything

is read. Base64 `content` uploads are unaffected by either variable.

Verifying Releases

Release archives are accompanied by a `checksums.txt` file and an optional

`checksums.txt.sig` produced by cosign

with the project's release keypair. Verifying both files lets you confirm

that the binary you downloaded was built by the project's release pipeline

and has not been tampered with in transit.

> Heads up: cosign signing was introduced mid-2026. Tags released

> before signing was wired up ship without a `.sig` file — verification

> applies from `v2.23.x` onward only, and only when the

> `COSIGN_PRIVATE_KEY` secret was configured at release time.

1. Install cosign

Follow the upstream

cosign installation guide

for your platform. Quick paths:

# Linux/macOS — pinned binary
COSIGN_VERSION=v2.4.1
curl -sSfL -o /usr/local/bin/cosign \
  "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64"
chmod +x /usr/local/bin/cosign

# macOS via Homebrew
brew install cosign

# Arch Linux
sudo pacman -S cosign

Confirm:

cosign version

2. Fetch the public key

The normative source for the cosign public key is the

`op1st-emea-b4mad`

GitOps repo — same source of truth that provisions the

`cosign-signing-key-artifacts` Secret in the `op1st-pipelines` namespace

where the release pipeline runs. This is the artifact-signing key that

signs release blobs (`checksums.txt.sig`); it is distinct from the

image-signing key `cosign-signing-key-images.pub` used in §5–§6 below.

Two ways to fetch it:

Branch-tip (live, follows future key rotations):

curl -sSfL -o cosign.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub

Commit-pinned (tamper-evident, recommended for CI/scripts):

curl -sSfL -o cosign.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/commit/cd3715fa8283a2069a2e3e299744a7b55b1b0260/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub

The commit-pinned permalink hashes its content into the URL — if anyone

ever rewrites the file at that commit, your download fails or mismatches.

Pin to the latest commit that you trust before adopting the key in

automation.

3. Download the release artifacts

Pick the tag you installed (e.g. `v2.23.1`) and grab the checksum file,

its signature, and the binary archive:

TAG=v2.23.1
VERSION="${TAG#v}"
BASE="https://git.b4mad.industries/agentic-forges/forgejo-mcp/releases/download/${TAG}"

curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt"
curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt.sig"
curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_linux_amd64.tar.gz"   # adjust os/arch

4. Verify the signature, then the checksum

Cosign verifies that `checksums.txt` was signed by the holder of the

private key matching `cosign.pub`. Once the checksum file is trusted, a

plain `sha256sum -c` check confirms the archive's integrity.

# Verify checksums.txt against the signature.
cosign verify-blob \
  --key cosign.pub \
  --signature "forgejo-mcp_${VERSION}_checksums.txt.sig" \
  "forgejo-mcp_${VERSION}_checksums.txt"
# Expected: "Verified OK"

# Verify the downloaded archive against the (now-trusted) checksums.
sha256sum --ignore-missing -c "forgejo-mcp_${VERSION}_checksums.txt"
# Expected: ": OK"

The checksum chain transitively covers the SBOMs and other per-archive

assets — verifying `checksums.txt` once is sufficient for everything

listed inside it.

5. Verify SLSA provenance for the release-tools image

The release-tools container image (used internally by the Tekton release

pipeline) carries SLSA v1.0 provenance generated by [Tekton

Chains](https://tekton.dev/docs/chains/). This attestation binds the image

digest to the exact PipelineRun, git commit, and builder identity that

produced it — providing supply-chain provenance beyond what the cosign

signature alone can attest.

Fetch the `cosign-signing-key-images` public key (a separate key from the

artifact-signing key above):

curl -sSfL -o cosign-images.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-images.pub

Verify the attestation against a specific image tag:

IMAGE_TAG=v1.0.0   # substitute the release-tools tag you want to verify
cosign verify-attestation \
  --type slsaprovenance \
  --key cosign-images.pub \
  "codeberg.org/operate-first/release-tools:${IMAGE_TAG}" \
  | jq .

A successful run prints the decoded in-toto statement (JSON). Check that

`predicate.buildDefinition.externalParameters.runSpec.params` references the

expected git revision, and `predicate.runDetails.builder.id` shows the

Tekton Chains builder.

> Note: SLSA provenance attestations are available from releases built

> after forgejo-mcp-46j (Tekton Chains support) landed. Earlier image tags

> carry only the cosign signature; they have no `verify-attestation` payload.

6. Verify the container image

The `git.b4mad.industries/agentic-forges/forgejo-mcp` application image (Option D)

is signed by the same `cosign-signing-key-images` key as the release-tools

image, carries an attached CycloneDX SBOM, and gets SLSA v1.0 provenance from

Tekton Chains. Reuse the `cosign-images.pub` key fetched above.

Verify the signature:

IMAGE_TAG=v2.24.0   # substitute the release you are pulling
cosign verify \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq .

Verify the SLSA provenance attestation:

cosign verify-attestation \
  --type slsaprovenance \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq .

Verify and download the signed CycloneDX SBOM attestation:

cosign verify-attestation \
  --type cyclonedx \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq -r '.payload | @base64d | fromjson | .predicate' > forgejo-mcp.cdx.json

> The SBOM is now a signed in-toto attestation (`cosign attest`), not an

> unsigned `attach sbom` artifact. `cosign download sbom` no longer applies.

Because the publish pipeline pushes by digest and only promotes the

`vX.Y.Z` / `latest` tags *after* signing and SBOM attachment succeed, any tag

you can pull is guaranteed to be signed.

Troubleshooting verification

• `Error: no matching signatures` — the `.sig` file is from a

different release, or `cosign.pub` is the wrong key. Re-download both

from the same tag.

• `Error: cannot read file: checksums.txt.sig` — release predates

cosign signing, or signing was skipped that run because the secret was

unset. Fall back to the checksum-only check (`sha256sum -c`), which

still detects in-transit corruption but not tampering.

• Mismatch between `cosign.pub` and the signature — confirm you

fetched the public key from a commit that includes the key in use at

the time of the release. If in doubt, fetch from `branch/main`.

Troubleshooting

Enable debug mode to see detailed logs:

forgejo-mcp --transport sse --url  --token  --debug

Or set the environment variable:

export FORGEJO_DEBUG=true

Custom User-Agent: If your Forgejo instance or proxy blocks the default `go-http-client` user agent, set a custom one:

# Via environment variable
export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"

# Or via CLI flag
forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url  --token

Getting Help

• Report issues
• View source code
• Chat on Matrix — `#forgejo-mcp:b4mad.net`

This repository is also mirrored on Radicle — a peer-to-peer code collaboration network. Clone via:

rad clone rad:z4PdPpsH9iJQcWfqTbxpFcWaZ9zPL

For Developers

See DEVELOPER.md for build instructions, architecture overview, and contribution guidelines.

Known Issues

• `go install ...@latest` needs a post-rename release — The Go module path

was `codeberg.org/goern/forgejo-mcp/v2` until the forge move; Go resolves

modules by the path declared in `go.mod`, so the

`git.b4mad.industries/...` path only becomes installable once a release is

tagged carrying the renamed `go.mod`. Until then, use the clone-and-build

workflow shown in Quick Start. The old

`go install codeberg.org/goern/forgejo-mcp/v2@latest` still resolves against

the read-only Codeberg mirror, but that mirror lags behind the current

release — do not rely on it. The earlier `replace`-directive blocker

(#67) is

gone; `go.mod` no longer contains one.

Contributors

forgejo-mcp is shaped by everyone who files issues, writes code, reviews PRs, and pushes the project forward. Thank you all. 🙏

Code contributors

Community contributors

Issue reporters and discussion participants who shaped the direction of the project:

Cyborg contributors

This project also received contributions from AI coding agents — submitted as regular PRs, reviewed by humans:

Want to contribute? Open an issue or pull request — all are welcome.

License

This project is open source. See the repository for license details.