MCP工具

1. Install

Option A: Using Go (Recommended)

git clone https://codeberg.org/goern/forgejo-mcp.git
cd forgejo-mcp
go install .

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

Note: go install codeberg.org/goern/forgejo-mcp/v2@latest does not work currently. See Known Issues.

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
 

 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.

1. Install cosign

Follow the upstream cosign installation guide for your platform. Quick paths:

```bash

Quick Start

Demos

End-to-end, copy-pasteable walkthroughs of the tools above — grouped by topic (labels, attachments, time tracking, notifications, orgs, bounded I/O code review, transport) — live in demos/. Each demo pairs real ./forgejo-mcp --cli invocations with the output they produced against codeberg.org.

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": "<your personal 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 <your-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
   

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

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 <your-token>

Configuration Options

You can configure the server using command-line arguments or environment variables:

Command-line arguments take priority over environment variables.

Via environment variable

export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"

CLI Mode

You can invoke any tool directly from the command line without running an MCP server. This is useful for shell scripts, CI/CD pipelines, and Claude Code skills.

```bash

Or via CLI flag

forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url <url> --token <token> ```

List recent workflow runs (text output)

forgejo-mcp --cli list_workflow_runs \ --args '{"owner":"goern","repo":"forgejo-mcp"}' \ --output=text

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 <url> --token <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:

```bash