pi-forgejo-mcp

A Pi extension for using Forgejo from Pi via the official forgejo-mcp CLI.

Use it to ask Pi to list repositories, inspect issues, create pull requests, read files, check workflow runs, manage releases, and call other Forgejo operations exposed by forgejo-mcp.

Install

First install the official Forgejo MCP CLI:

go install codeberg.org/goern/forgejo-mcp/v2@latest

Make sure forgejo-mcp is on your PATH:

forgejo-mcp --help

Install by asking Pi

If you already have Pi installed, you can paste this prompt into Pi. It asks Pi to check prerequisites, install the extension, and then explain the remaining authentication steps:

Please install the Forgejo MCP Pi extension for me.

Before installing, remind me that Pi packages/extensions run with my local user permissions. Ask me for confirmation before running installation commands.

Do the setup:
1. Check whether `forgejo-mcp` is installed and on PATH.
2. If it is missing, check whether `go` is available. If Go is available, install the official CLI with:
   `go install codeberg.org/goern/forgejo-mcp/v2@latest`
   Then verify `forgejo-mcp --help` works. If it does not, tell me to add `$(go env GOPATH)/bin` to PATH or configure `FORGEJO_MCP_COMMAND`.
   If Go is not available, stop and tell me to install Go or configure `FORGEJO_MCP_COMMAND`.
3. Install the Pi package:
   `pi install git:codeberg.org/ozzy92/pi-forgejo-mcp@main`
4. Do not ask me to paste a token into chat. Tell me to set `FORGEJO_URL` and `FORGEJO_ACCESS_TOKEN` in the shell that launches Pi, using 1Password, Bitwarden, direnv, or another secret store.
5. Tell me to restart Pi or run `/reload`.
6. After reload/restart, tell me to run: `Check Forgejo MCP status.`

For repeatable installs, ask Pi to install a tagged release such as git:codeberg.org/ozzy92/pi-forgejo-mcp@v0.1.0 instead of main.

Manual install

Install this Pi package from Codeberg:

pi install git:codeberg.org/ozzy92/pi-forgejo-mcp@main

For repeatable installs, install a tagged release instead of main:

pi install git:codeberg.org/ozzy92/pi-forgejo-mcp@v0.1.0

Restart Pi or run /reload in an existing Pi session.

Security: Pi packages and extensions run with your local user permissions. Review the source before installing third-party packages.

Authenticate with Forgejo

Create a Forgejo personal access token with the permissions you need for the operations you want Pi to perform.

The token lives in the environment of the pi process:

export FORGEJO_URL="https://codeberg.org" # or your Forgejo instance URL
export FORGEJO_ACCESS_TOKEN="<your personal access token>"
pi

Do not commit the token. Do not put it in this repository, package.json, Pi settings, prompts, or session files.

Good places to keep the token:

• your password manager, injected into the shell before launching Pi
• a local, gitignored shell file sourced by your shell profile
• a direnv .envrc file that is not committed
• CI/secret-store environment variables for non-interactive runs

Example with 1Password CLI:

export FORGEJO_URL="https://codeberg.org"
export FORGEJO_ACCESS_TOKEN="$(op read 'op://Private/Codeberg Forgejo/token')"
pi

Example with Bitwarden CLI:

export BW_SESSION="$(bw unlock --raw)"
export FORGEJO_URL="https://codeberg.org"
export FORGEJO_ACCESS_TOKEN="$(bw get password 'Codeberg Forgejo token')"
pi

See SECURITY.md for vulnerability reporting, token-handling guidance, and local execution notes.

Try it in Pi

Ask Pi things like:

Check Forgejo MCP status.
List Forgejo MCP issue tools.
Describe the list_repo_issues Forgejo MCP tool.
List open issues in my-org/my-repo.
Create an issue in my-org/my-repo titled "Improve docs" with body "Add screenshots".
Show recent workflow runs for my-org/my-repo.

Pi will usually discover or describe the Forgejo operation first, then call it with JSON arguments.

Tools provided to Pi

When Pi loads this extension, it registers four tools:

Tool	Purpose
forgejo_mcp_status	Check whether forgejo-mcp is installed and whether runtime auth env vars are present.
forgejo_mcp_list_tools	List operations exposed by the installed forgejo-mcp binary, optionally filtered by domain/query.
forgejo_mcp_describe_tool	Show the parameters for one Forgejo MCP operation.
forgejo_mcp_call	Invoke one Forgejo MCP operation with JSON arguments.

If you are driving Pi programmatically, forgejo_mcp_call accepts this shape:

{
  "tool": "list_repo_issues",
  "args": {
    "owner": "my-org",
    "repo": "my-repo",
    "state": "open"
  }
}

How it works

This extension does not implement the Forgejo API itself. It shells out to the official CLI:

forgejo-mcp --cli <operation> --args '<json>' --output=json

Read-only discovery (forgejo_mcp_list_tools and forgejo_mcp_describe_tool) uses dummy local environment variables because forgejo-mcp requires configuration even for local help output.

Real Forgejo calls use FORGEJO_URL and FORGEJO_ACCESS_TOKEN from the Pi process environment.

Large outputs are truncated to Pi's default tool-output limit, and the full output is written to a temp file. Captured stdout/stderr is sanitized so the configured access token is replaced before tool results are returned to Pi.

Safety model

Operations whose names look mutating (create_*, update_*, delete_*, merge_*, mark_*, etc.) ask for confirmation in interactive Pi sessions.

In non-interactive modes, mutating operations are blocked unless you explicitly set:

export FORGEJO_MCP_ALLOW_MUTATIONS=true

You can disable interactive confirmations with:

export FORGEJO_MCP_CONFIRM_MUTATIONS=false

When confirmations are disabled, mutating operations are treated like non-interactive runs and still require:

export FORGEJO_MCP_ALLOW_MUTATIONS=true

Configuration

Variable	Default	Purpose
FORGEJO_URL	required	Forgejo instance URL, for example https://codeberg.org.
FORGEJO_ACCESS_TOKEN	required	Forgejo personal access token.
FORGEJO_MCP_COMMAND	forgejo-mcp	Binary to execute. Use this if forgejo-mcp is not on PATH.
FORGEJO_MCP_TIMEOUT_MS	60000	Timeout per CLI call.
FORGEJO_MCP_MAX_CAPTURE_BYTES	26214400	Maximum stdout/stderr captured before killing the process.
FORGEJO_MCP_CONFIRM_MUTATIONS	true in UI mode	Set to false to skip interactive confirmation.
FORGEJO_MCP_ALLOW_MUTATIONS	unset	Required for mutating operations when no confirmation is taken.

Local development

git clone https://codeberg.org/ozzy92/pi-forgejo-mcp.git
cd pi-forgejo-mcp
npm install
npm run check
pi -e .

npm run check runs TypeScript, ESLint, Prettier, and Vitest.

For local testing against a real Forgejo instance, copy the example environment file and source it before launching Pi:

cp .env.example .env.local
# edit .env.local with your own token
set -a; source .env.local; set +a
pi -e .

Pi does not automatically load .env files. The .env and .env.* patterns are gitignored; keep real tokens out of commits.

Or install the local package globally while developing:

pi install /absolute/path/to/pi-forgejo-mcp

License

MIT