foregejo-mcp-container

Container image for forgejo-mcp, a Model Context Protocol (MCP) server for Forgejo.

Overview

This repository contains the Containerfile and CI pipeline to build, scan, and publish a container image that packages the upstream forgejo-mcp binary. The upstream source is compiled inside the container build using a current Go toolchain — no local Go installation is required.

Build pipeline

Builds are handled by the Forgejo Actions workflow at .forgejo/workflows/build.yml. The pipeline runs on every push and can also be triggered manually from the Forgejo UI.

What the pipeline does

1. Lint — runs bash -n and shellcheck against any shell scripts in the repository.
2. Resolve version — auto-detects the latest forgejo-mcp release from the Forgejo API. A specific release can be pinned when triggering the workflow manually, which is useful for reproducible builds.
3. Build — compiles the upstream source inside a multi-stage container build and loads the image into the local Docker daemon. BuildKit layer caching keeps repeat builds fast.
4. Scan — runs a Trivy vulnerability scan against the locally loaded image. The pipeline fails here if any HIGH or CRITICAL findings are present; nothing is pushed to the registry until the image is clean.
5. Push — pushes the image to code.paulg.it/paulgit/forgejo-mcp on merges to main only. Auto-detected builds receive both a versioned tag and :latest; manually pinned builds receive a versioned tag only.

Containerfile

Two-stage build:

1. Build stage — downloads the forgejo-mcp source archive for the target release, compiles it with Go, and applies any dependency patches needed to address known CVEs.
2. Final stage — copies the compiled binary into a minimal distroless image.

Running the MCP server

Copy .env.example to .env, fill in your Forgejo instance URL and access token, then start the server in stdio mode:

cp .env.example .env
docker compose run --rm forgejo-mcp

To wire the server into an MCP client such as Claude Desktop, point it at the Compose stack rather than a URL:

{
  "mcpServers": {
    "forgejo": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yaml",
        "run", "--rm", "forgejo-mcp"
      ]
    }
  }
}

Prerequisites

• Docker with Buildx (local use)
• A Forgejo personal access token with repo and issue scopes