Skip to content
Back to search

forgejo-mcp

MIRROR ONLY!! This Model Context Protocol (MCP) server provides tools and resources for interacting with the Forgejo (specifically Codeberg.org) REST API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/goern/forgejo-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/goern/forgejo-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/goern--forgejo-mcp/badge.svg)](/listings/goern--forgejo-mcp)

HTML

<a href="/listings/goern--forgejo-mcp"><img src="/api/listings/goern--forgejo-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:** you can also install straight from the module path, without > cloning: > > ```bash > go install git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest > ```

**Option B: Download Binary**

Download the latest release from the [releases page](https://git.b4mad.industries/agentic-forges/forgejo-mcp/releases).

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="<your personal 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:v3.1.0 --help

| Tag | Meaning | |-----------------|----------------------------------------------------------------| | `vMAJOR.MINOR.PATCH` | Immutable — the exact release (e.g. `v3.1.0`). Use in production. | | `latest` | Moving — tracks the most recent release. Convenience only. |

The image is single-arch (`linux/amd64`), signed with cosign, and carries an attached CycloneDX SBOM. See [Verify the container image](#6-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": "<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

2. Clients include their specific token in each request: - `Authorization: token <token>` (Forgejo style) - `Authorization: Bearer <token>` (OAuth2/MCP style) - Note: The scheme (`token` or `Bearer`) is case-insensitive.

See [demos/multi-tenant-http.md](demos/multi-tenant-http.md) for a copy-pasteable walkthrough.

Exposing the server to a network

By default the `sse` and `http` transports listen on loopback only, so nothing outside

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,031 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Forgejo MCP Server
  2. > **📦 This project has moved.** Development, issues, releases, and container
  3. > images now live at
  4. > **<https://git.b4mad.industries/agentic-forges/forgejo-mcp>**.
  5. > The Codeberg repository at `codeberg.org/goern/forgejo-mcp` remains only as a
  6. > read-only mirror, and its container registry no longer publishes images —
  7. > pull from `git.b4mad.industries/agentic-forges/forgejo-mcp` instead. Issue
  8. > numbers are preserved across the move. Contributions from humans **and**
  9. > AI agents are welcome at the new location.
  10. >
  11. > ```bash
  12. > git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git
  13. > ```
  14. >
  15. > If you have a remote or a bookmark pointing at `forgejo.b4mad.net`, that is
  16. > the **same** forge under its previous name — renamed 2026-07-29, not moved
  17. > again. The old name still resolves and serves port 2222 with the same host
  18. > key, so existing clones keep working; repoint them at your leisure:
  19. >
  20. > ```bash
  21. > git remote set-url origin \
  22. > ssh://git@git.b4mad.industries:2222/agentic-forges/forgejo-mcp.git
  23. > ssh-keyscan -p 2222 git.b4mad.industries >> ~/.ssh/known_hosts
  24. > ```
  25. Connect your AI assistant to Forgejo repositories. Manage issues, pull requests, files, and more through natural language.
  26. ## What It Does
  27. Forgejo MCP Server is an integration plugin that connects Forgejo with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) systems. Once configured, you can interact with your Forgejo repositories through any MCP-compatible AI assistant like Claude, Cursor, or VS Code extensions.
  28. **Example commands you can use:**
  29. - "List all my repositories"
  30. - "Create an issue titled 'Bug in login page'"
  31. - "Show me open pull requests in my-org/my-repo"
  32. - "Get the contents of README.md from the main branch"
  33. - "Show me the latest Actions workflow runs in agentic-forges/forgejo-mcp"
  34. ## Quick Start
  35. ### 1. Install
  36. **Option A: Using Go (Recommended)**
  37. ```bash
  38. git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git
  39. cd forgejo-mcp
  40. go install .
  41. ```
  42. Ensure `$GOPATH/bin` (typically `~/go/bin`) is in your PATH.
  43. > **Note:** you can also install straight from the module path, without
  44. > cloning:
  45. >
  46. > ```bash
  47. > go install git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest
  48. > ```
  49. **Option B: Download Binary**
  50. Download the latest release from the [releases page](https://git.b4mad.industries/agentic-forges/forgejo-mcp/releases).
  51. For Arch Linux, use your favorite AUR helper:
  52. ```bash
  53. yay -S forgejo-mcp # builds from source
  54. yay -S forgejo-mcp-bin # uses pre-built binary
  55. ```
  56. **Option C: Nix / NixOS**
  57. You can run the server directly using the Nix package manager:
  58. ```bash
  59. nix-shell -p forgejo-mcp
  60. ```
  61. Or using Flakes:
  62. ```bash
  63. nix run nixpkgs#forgejo-mcp
  64. ```
  65. > **Note:** `forgejo-mcp` is currently only available in the `unstable` channel and is not yet part of the 25.11 stable release.
  66. **Option D: Container image**
  67. A signed multi-stage OCI image is published on every release to
  68. `git.b4mad.industries/agentic-forges/forgejo-mcp`. Run the server without building from source:
  69. ```bash
  70. # Latest release
  71. podman run --rm -i \
  72. -e FORGEJO_ACCESS_TOKEN="<your personal access token>" \
  73. git.b4mad.industries/agentic-forges/forgejo-mcp:latest \
  74. --transport stdio --url https://your-forgejo-instance.org
  75. # Or pin a specific version
  76. podman run --rm -i git.b4mad.industries/agentic-forges/forgejo-mcp:v3.1.0 --help
  77. ```
  78. | Tag | Meaning |
  79. |-----------------|----------------------------------------------------------------|
  80. | `vMAJOR.MINOR.PATCH` | Immutable — the exact release (e.g. `v3.1.0`). Use in production. |
  81. | `latest` | Moving — tracks the most recent release. Convenience only. |
  82. The image is single-arch (`linux/amd64`), signed with cosign, and carries an
  83. attached CycloneDX SBOM. See [Verify the container image](#6-verify-the-container-image)
  84. to check the signature and provenance before running.
  85. ### 2. Get Your Access Token
  86. 1. Log into your Forgejo instance
  87. 2. Go to **Settings** → **Applications** → **Access Tokens**
  88. 3. Create a new token with the permissions you need (repo, issue, etc.)
  89. ### 3. Configure Your AI Assistant
  90. Add this to your MCP configuration file:
  91. **For stdio mode** (most common):
  92. ```json
  93. {
  94. "mcpServers": {
  95. "forgejo": {
  96. "command": "forgejo-mcp",
  97. "args": [
  98. "--transport", "stdio",
  99. "--url", "https://your-forgejo-instance.org"
  100. ],
  101. "env": {
  102. "FORGEJO_ACCESS_TOKEN": "<your personal access token>",
  103. "FORGEJO_USER_AGENT": "forgejo-mcp/1.0.0"
  104. }
  105. }
  106. }
  107. }
  108. ```
  109. **For streamable HTTP mode** (recommended for remote/Claude.ai):
  110. ```json
  111. {
  112. "mcpServers": {
  113. "forgejo": {
  114. "url": "http://localhost:8080/mcp"
  115. }
  116. }
  117. }
  118. ```
  119. When using streamable HTTP mode, start the server first:
  120. ```bash
  121. forgejo-mcp --transport http --url https://your-forgejo-instance.org --token <your-token>
  122. ```
  123. **Multi-tenant HTTP mode** (optional):
  124. 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.
  125. 1. Start the server (optionally without any global token):
  126. ```bash
  127. forgejo-mcp --transport http --url https://your-forgejo-instance.org
  128. ```
  129. 2. Clients include their specific token in each request:
  130. - `Authorization: token <token>` (Forgejo style)
  131. - `Authorization: Bearer <token>` (OAuth2/MCP style)
  132. - Note: The scheme (`token` or `Bearer`) is case-insensitive.
  133. See [demos/multi-tenant-http.md](demos/multi-tenant-http.md) for a copy-pasteable walkthrough.
  134. #### Exposing the server to a network
  135. By default the `sse` and `http` transports listen on loopback only, so nothing outside
  136. this machine can reach them. This follows the Model Context Protocol's guidance for
  137. locally-run servers, and it is a change in behaviour: earlier versions listened on
  138. every network interface. The default, `localhost`, binds both loopback families, so a
  139. client that resolves `localhost` to either `127.0.0.1` or `::1` connects. If the port is
  140. already taken on either family the server refuses to start, rather than serve on the
  141. other family while some clients reach whatever holds the port. A family the machine
  142. cannot use at all — IPv6 disabled, say — is skipped, and the startup log says so.
  143. Pass an address rather than a name — `--host 127.0.0.1` or `--host ::1` — to bind that
  144. family alone. Use it when the other family is unusable on this machine in a way the
  145. server cannot recognise as "absent", so that it would otherwise refuse to start.
  146. **If you run the server in a container, or serve remote clients, you must now say so
  147. explicitly.** The default will not accept connections from outside the machine — or,
  148. in a container, from outside the container:
  149. - set `--host` to an address the network can reach (`0.0.0.0` for all interfaces,
  150. which is the usual choice inside a container);
  151. - and set `--allowed-hosts` to the host names your clients use. This is required, not
  152. optional: the server refuses to start on a network-reachable address without it,
  153. rather than starting and rejecting every request.
  154. Requests are refused with `403 Forbidden` when their `Host` header is not one you
  155. declared. Loopback names are always accepted on a loopback listener, so declaring a
  156. proxy's hostname does not stop you connecting directly from the same machine.
  157. **Browser clients.** A request carrying an `Origin` header is refused unless that
  158. origin is listed in `--allowed-origins`, which is empty by default. Origins are
  159. compared in full — scheme, host and port — because an `Origin`'s port belongs to the
  160. page making the request, not to this server. Requests with no `Origin` header at all
  161. are unaffected, which is the normal case: an MCP client is not a browser.
  162. #### Authentication on `sse` and `http`
  163. On these transports every request must carry its own `Authorization` header. A request
  164. without one is refused with `401 Unauthorized`, rather than being served using the
  165. server's own configured token. This is what the multi-tenant setup above expects
  166. anyway, and it is why that setup is safe to expose.
  167. On `stdio` the configured token still stands in for an absent header exactly as
  168. before. Nothing about `stdio` changes.
  169. The server does not check a token when it arrives; Forgejo does, on the first call
  170. that reaches it. When Forgejo rejects the token (unknown, revoked or expired), the
  171. call fails with JSON-RPC error code `-32004` and the message `Forgejo rejected the
  172. access token`. On `http` the response also carries status `401` and
  173. `WWW-Authenticate: Bearer error="invalid_token"`, which is what makes an OAuth MCP
  174. client refresh or re-authorize instead of reporting a tool error. On `sse`, and on
  175. an `http` response that is already streaming, only the error code tells. A call
  176. that never reaches Forgejo, such as `tools/list`, is answered normally. A token that
  177. lacks a scope gets an ordinary error, not `-32004`.
  178. Forgejo repeats a rejected token in its error message. The server replaces that
  179. message before anything reads it, so the token never appears in a response or in
  180. the server's log, whichever token it was: a client's or the operator's own.
  181. If you run a single-user deployment over `sse` or `http` and want the old behaviour,
  182. `--allow-operator-token-fallback` restores it. Understand what it means before you use
  183. it: any client that can reach the port acts as the identity behind your token, without
  184. presenting a credential. The startup log says so, loudly, whenever it is on.
  185. **For SSE mode** (legacy HTTP-based):
  186. ```json
  187. {
  188. "mcpServers": {
  189. "forgejo": {
  190. "url": "http://localhost:8080/sse"
  191. }
  192. }
  193. }
  194. ```
  195. When using SSE mode, start the server first:
  196. ```bash
  197. forgejo-mcp --transport sse --url https://your-forgejo-instance.org --token <your-token>
  198. ```
  199. #### Notification streams and the heartbeat
  200. On `sse` and `http` the server holds a stream open to deliver its own messages
  201. (notifications, progress, server requests). While a session is idle that stream
  202. carries nothing, and clients, proxies and NAT devices drop a stream that stays
  203. silent long enough; one MCP client aborts after six minutes. The server therefore
  204. writes a JSON-RPC `ping` into the stream every `--heartbeat` interval, `30s` by
  205. default. Set `--heartbeat 0` to restore the previous, silent behaviour.
  206. #### Remote operation as an OAuth resource server
  207. With `--auth-mode resource-server`, the `http` transport becomes an OAuth 2.0
  208. resource server as the MCP authorization specification defines it. Clients no
  209. longer send a Forgejo token. They log in at an OpenID Connect provider you choose
  210. and send its JWT access token. The server validates that token, signs a JWT that
  211. lives five minutes for the caller, and presents it to Forgejo through a Forgejo 16
  212. Authorized Integration. No forge token is configured anywhere, and the caller's
  213. access token never reaches Forgejo.
  214. The mode needs:
  215. - Forgejo 16.0 or newer;
  216. - an OpenID Connect provider that issues JWT access tokens and can add a per-user
  217. claim (default `forgejo_aud`) holding the audience of that user's Authorized
  218. Integration;
  219. - a public HTTPS origin for the server, because Forgejo fetches the server's issuer
  220. documents from it;
  221. - a signing key file: EC P-256 or P-384, Ed25519, or RSA of at least 2048 bits.
  222. ```bash
  223. forgejo-mcp --transport http --url https://forgejo.example.org \
  224. --host 0.0.0.0 --allowed-hosts mcp.example.org \
  225. --auth-mode resource-server \
  226. --authorization-server https://id.example.org \
  227. --resource https://mcp.example.org/mcp \
  228. --forgejo-jwt-issuer https://mcp.example.org/issuer \
  229. --forgejo-jwt-signing-key-file /run/credentials/forgejo-mcp.service/signing-key
  230. ```
  231. The mode is opt-in: without `--auth-mode`, everything above behaves as before. In
  232. this mode the server answers only `/mcp`, the protected resource metadata, and the
  233. discovery document and key set under the issuer path. It refuses to start on a
  234. configuration it cannot serve safely, and the refusal names the setting to fix.
  235. The signing key acts for every user whose integration trusts the issuer, so guard
  236. it like the forge token it replaces.
  237. If Forgejo rejects the JWT signed for a caller, for example because the caller's
  238. Authorized Integration was deleted, the call fails with `-32603` and a message
  239. saying so, and the server logs a warning. It does not answer `401`: the caller's
  240. login is valid, and logging in again would not fix the integration.
  241. - [Operator guide](docs/oauth-resource-server/operator.md): identity provider
  242. requirements, deployment order, proxy rules, key rotation, and a worked Zitadel
  243. example.
  244. - [User guide](docs/oauth-resource-server/user.md): creating the Authorized
  245. Integration, the mandatory `sub` claim rule, and configuring an MCP client.
  246. ### 4. Start Using It
  247. Open your MCP-compatible AI assistant and try:
  248. ```
  249. List all my repositories
  250. ```
  251. ## Available Tools
  252. | Tool | Description |
  253. |------|-------------|
  254. | **User** | |
  255. | `get_my_user_info` | Get information about the authenticated user |
  256. | `check_notifications` | Check and list user notifications |
  257. | `get_notification_thread` | Get detailed info on a single notification thread |
  258. | `mark_notification_read` | Mark a single notification thread as read |
  259. | `mark_all_notifications_read` | Acknowledge all notifications |
  260. | `list_repo_notifications` | Filter notifications scoped to a single repository |
  261. | `mark_repo_notifications_read` | Mark all notifications in a specific repo as read |
  262. | `search_users` | Search for users |
  263. | **Repositories** | |
  264. | `list_my_repos` | List all repositories you own |
  265. | `get_repo` | Get a single repository by owner and name |
  266. | `create_repo` | Create a new repository |
  267. | `fork_repo` | Fork a repository |
  268. | `edit_repo` | Edit repository settings. Only fields you pass change; omitted fields are left unchanged. Providing no fields is an error. |
  269. | `search_repos` | Search for repositories |
  270. | **Topics** | |
  271. | `list_repo_topics` | List a repository's topics. Bounded by `page` (default 1) + `limit` (default 100); returns `{topics, page, limit, count}`. |
  272. | `set_repo_topics` | Replace all topics. `topics` is a required comma-separated string; an empty string clears. Invalid names are rejected before the request. |
  273. | `add_repo_topic` | Add one topic |
  274. | `delete_repo_topic` | Delete one topic |
  275. | **Branches** | |
  276. | `list_branches` | List all branches in a repository |
  277. | `create_branch` | Create a new branch |
  278. | `delete_branch` | Delete a branch |
  279. | **Branch Protection** | |
  280. | `list_branch_protections` | List a repository's branch protection rules. Bounded by `page` (1-based) + `limit` (page size); the response echoes `page`/`limit` so callers can fetch the next page. |
  281. | `get_branch_protection` | Get a single rule by `rule` name |
  282. | `create_branch_protection` | Create a rule. Requires `branch_name`; `status_check_contexts` is a comma-separated list of required checks (e.g. `"ci/build,ci/test"`). |
  283. | `edit_branch_protection` | Edit a rule by `rule` name. Only fields you pass change; omitted fields are left unchanged. |
  284. | `delete_branch_protection` | Delete a rule by `rule` name |
  285. | **Webhooks** | |
  286. | `list_repo_hooks` | List repository webhooks. Bounded by `page` (default 1) + `limit` (default 30, no server-imposed ceiling); returns `total_count` when Forgejo reports `X-Total-Count`. |
  287. | `get_repo_hook` | Get a single repository webhook by ID |
  288. | `create_repo_hook` | Create a repository webhook. The secret is accepted but never echoed in the response. |
  289. | `edit_repo_hook` | Edit a repository webhook. Only fields you pass change; omitted fields are left unchanged. |
  290. | `delete_repo_hook` | Delete a repository webhook by ID |
  291. | `test_repo_hook` | Trigger a test delivery for a repository webhook — WARNING: triggers a live HTTP delivery |
  292. | **Files** | |
  293. | `get_file_content` | Get the content of a file. Optional `start_line`/`end_line` request a 1-indexed inclusive line range (clamps to file extent; ignored when `with_metadata=true`). |
  294. | `list_repo_contents` | List files and directories at a path. `path=""` lists the repository root. Returns one level; for a full tree use `get_repo_tree` with `recursive=true`. |
  295. | `get_repo_tree` | Get the Git tree. `recursive=true` returns the complete file tree in one response (subject to the server's tree-endpoint size cap); `recursive=false` (default) returns one level. |
  296. | `create_file` | Create a new file. Supply exactly one of plain-text `content` or binary-safe `content_base64` (strict standard Base64). |
  297. | `update_file` | Update an existing file. Supply exactly one of plain-text `content` or binary-safe `content_base64` (strict standard Base64). |
  298. | `delete_file` | Delete a file |
  299. | `change_files` | Atomically create, update, and delete multiple files in one native Forgejo commit; create/update operations accept `content` or `content_base64`. |
  300. | **Commits** | |
  301. | `list_repo_commits` | List commits in a repository |
  302. | `get_commit_statuses` | List per-context commit statuses for a full 40-character SHA. Bounded by `page` (default 1) + `limit` (default 30, maximum 50); returns `{sha, statuses, page, limit, count, total_count}` — `total_count` is present only when Forgejo reports `X-Total-Count`. Combined aggregate stays on the commit status resource. Not Actions runs (`list_workflow_runs`). |
  303. | **Issues** | |
  304. | `list_repo_issues` | List issues in a repository (page/limit). Optional `sort` orders server-side: `relevance`, `latest`, `oldest`, `recentupdate`, `leastupdate`, `mostcomment`, `leastcomment`, `nearduedate`, `farduedate` (the last two are the due-date directions). |
  305. | `search_issues` | Search issues across every repository of one owner (page/limit); returns `{issues,page,limit,count,has_next,total_count}` — `total_count` is present only when Forgejo reports `X-Total-Count` |
  306. | `get_issue_by_index` | Get a specific issue |
  307. | `create_issue` | Create a new issue. Optional `labels` (comma-separated names or IDs), `assignees` (comma-separated usernames) and `milestone` (numeric ID) are applied by the same request that creates the issue. |
  308. | `add_issue_labels` | Add labels to an issue. `labels` takes comma-separated label names or numeric IDs; an unrecognised name is an error and nothing is applied. |
  309. | `remove_issue_labels` | Remove labels from an issue. `labels` takes comma-separated label names or numeric IDs. |
  310. | `update_issue` | Update an existing issue (requires numeric milestone ID). `due_date` sets the deadline (RFC3339); `clear_due_date=true` removes it. The two are mutually exclusive — setting both is an error, and omitting both leaves the deadline unchanged. `set_labels` replaces the issue's entire label set (names or IDs); an empty string clears every label. |
  311. | `issue_state_change` | Open or close an issue |
  312. | `list_issue_dependencies` | List issues the given issue depends on. Bounded by `page` (1-based) + `limit` (page size); the response echoes `page`/`limit` so callers can fetch the next page. |
  313. | `list_issue_dependents` | List issues that depend on the given issue. Bounded by `page` (1-based) + `limit` (page size); the response echoes `page`/`limit` so callers can fetch the next page. |
  314. | `add_issue_dependency` | Make one issue depend on another. The dependency may live in a different repository: optional `depends_on_owner`/`depends_on_repo` default to `owner`/`repo`. |
  315. | `remove_issue_dependency` | Remove a dependency from an issue. For a cross-repo dependency, optional `dependency_owner`/`dependency_repo` default to `owner`/`repo`. |
  316. | `list_repo_milestones` | List milestones with their IDs (use with `update_issue`) |
  317. | `list_repo_labels` | List labels with their IDs. Merges org-level labels for org-owned repos (set `include_org_labels=false` to opt out). Each entry carries a `scope` field (`"repo"` or `"org"`), plus `exclusive` and `is_archived` (`false` is present, not omitted). |
  318. | `list_org_labels` | List organization-level labels with their IDs. The assignment tools accept label names directly, so this is for discovery and for the rare name that exists in both the repo and the org scope. Each entry includes `exclusive` and `is_archived`. |
  319. | `create_repo_label` | Create a repository label (`name`, `color` as 6-digit hex, optional `description`, `exclusive`, `is_archived`). `exclusive=true` requires a scoped name (a `/` not at either end). Returns the numeric `id`; `add_issue_labels` also takes the name. |
  320. | `edit_repo_label` | Edit a repository label (PATCH — only supplied fields change: `name`, `color`, `description`, `exclusive`, `is_archived`). Exclusive-only edit does not re-read the current name. |
  321. | `delete_repo_label` | Delete a repository label. Refuses by default when the label is in use (reports count); set `delete_mode=force` to override. |
  322. | `get_repo_label` | Get a single repository label by numeric `id`. Includes `exclusive` and `is_archived`. |
  323. | `create_org_label` | Create an organization-level label. Same fields as `create_repo_label`. |
  324. | `edit_org_label` | Edit an organization-level label (PATCH semantics, including `exclusive` and `is_archived`). |
  325. | `delete_org_label` | Delete an organization-level label. In-use guard counts across visible org repos (best-effort); `delete_mode=force` overrides. |
  326. | `get_org_label` | Get a single organization-level label by numeric `id`. Includes `exclusive` and `is_archived`. |
  327. | **Comments** | |
  328. | `list_issue_comments` | List comments on an issue or PR |
  329. | `get_issue_comment` | Get a specific comment |
  330. | `create_issue_comment` | Add a comment to an issue or PR |
  331. | `edit_issue_comment` | Edit a comment |
  332. | `delete_issue_comment` | Delete a comment |
  333. | **Pull Requests** | |
  334. | `list_repo_pull_requests` | List pull requests in a repository |
  335. | `get_pull_request_by_index` | Get a specific pull request |
  336. | `create_pull_request` | Create a new pull request |
  337. | `update_pull_request` | Update an existing pull request |
  338. | `list_pull_reviews` | List reviews for a pull request |
  339. | `get_pull_review` | Get a specific pull request review |
  340. | `list_pull_review_comments` | List comments on a pull request review |
  341. | `list_pull_request_files` | List changed files in a pull request (paginated). Use the returned filenames as the `file_path` argument to `get_pull_request_diff`. |
  342. | `get_pull_request_diff` | Get the unified diff of a pull request. Optional `file_path` returns only that file's hunks (matches on either pre- or post-rename path). |
  343. | `merge_pull_request` | Merge a pull request (style: merge/rebase/rebase-merge/squash; optional title/message/delete-branch/force-merge/wait-for-checks). |
  344. | `create_pull_review` | Create a review on a pull request (state: APPROVED/REQUEST_CHANGES/COMMENT) with optional inline comments. |
  345. | `submit_pull_review` | Submit a pending pull request review |
  346. | `dismiss_pull_review` | Dismiss a pull request review |
  347. | `delete_pull_review` | Delete a pending pull request review |
  348. | `create_review_requests` | Request reviews from specific users or teams |
  349. | `delete_review_requests` | Cancel pending review requests |
  350. | **Packages** | |
  351. | `list_packages` | List package versions of a user or org (one row per version). Optional `type` and `q`. Server-paged via `page`/`limit` (default 30, max 50). Envelope `{packages, page, limit, count, has_next, total_count?}`. A missing owner is an error, not an empty list |
  352. | `get_package` | Get one package version. Does not embed owner/creator users |
  353. | `delete_package` | Delete one package version (not every version of the name). No preflight. 4xx/5xx stay errors |
  354. | `list_package_files` | List files of one package version. Client-paged via `page`/`limit` (default 30, max 50); envelope `{files, page, limit, count, has_next, total_count}` (`total_count` is the fetched list length) |
  355. | **Actions** | |
  356. | `dispatch_workflow` | Trigger a workflow run via `workflow_dispatch` event |
  357. | `list_workflow_runs` | List workflow runs with optional filtering by status, event, run number, or SHA |
  358. | `get_workflow_run` | Get details of a specific workflow run by database ID |
  359. | `list_action_run_jobs` | List jobs for a Forgejo v16+ workflow run with client-side `page` and `limit` bounds |
  360. | `get_action_job_logs` | Read a Forgejo v16+ job log with resumable `offset` and `max_bytes` bounds; defaults to the tail |
  361. | `cancel_workflow_run` | Cancel a pending or running Forgejo v16+ workflow run. Already-finished runs also return success (HTTP 204); the run is left unchanged |
  362. | `delete_workflow_run` | Delete a completed Forgejo v16+ workflow run. A live run is an API error. Removes the run and its job logs; Forgejo marks that run's artifacts deleted |
  363. | `list_action_run_artifacts` | List artifacts of a Forgejo v16+ workflow run. Server-paged via `page`/`limit` (default 30, max 50); optional `name` filter. Envelope `{artifacts, page, limit, count, total_count?}` |
  364. | `get_action_artifact` | Get metadata for one Forgejo v16+ Actions artifact. Does not download the zip |
  365. | `list_repo_action_secrets` | List a repository's Actions secrets (names only; Forgejo never returns values). Client-paged via `page`/`limit` (default 30, max 50) |
  366. | `create_or_update_repo_action_secret` | Create or update a repository Actions secret. Overwrites any existing secret with the same name; the value is never echoed back |
  367. | `delete_repo_action_secret` | Delete a repository Actions secret |
  368. | `list_org_action_secrets` | List an organization's Actions secrets (names only; Forgejo never returns values). Client-paged via `page`/`limit` (default 30, max 50) |
  369. | `create_or_update_org_action_secret` | Create or update an organization Actions secret. Overwrites any existing secret with the same name; the value is never echoed back |
  370. | `delete_org_action_secret` | Delete an organization Actions secret |
  371. | **Organizations** | |
  372. | `list_my_orgs` | List my organizations |
  373. | `list_user_orgs` | List a user's organizations |
  374. | `get_org` | Get organization details |
  375. | `create_org` | Create an organization |
  376. | `edit_org` | Edit organization settings |
  377. | `delete_org` | Delete an organization — **destructive and irreversible**: all repos, teams and data are permanently removed |
  378. | `list_org_members` | List members of an organization |
  379. | `check_org_membership` | Check if a user is a member of an organization |
  380. | `remove_org_member` | Remove a member from an organization |
  381. | `list_org_teams` | List teams in an organization |
  382. | `search_org_teams` | Search for teams in an organization |
  383. | `create_org_team` | Create a team in an organization |
  384. | `add_team_member` | Add a user to a team |
  385. | `remove_team_member` | Remove a user from a team |
  386. | `add_team_repo` | Add a repository to a team |
  387. | `remove_team_repo` | Remove a repository from a team |
  388. | **Time Tracking** | |
  389. | `list_issue_tracked_times` | List tracked time entries on an issue or PR |
  390. | `list_repo_tracked_times` | List tracked time entries across a repository |
  391. | `list_my_tracked_times` | List your own tracked time entries |
  392. | `add_issue_time` | Log time against an issue or PR (accepts seconds or duration like `15m`) |
  393. | `reset_issue_time` | Delete ALL tracked time entries on an issue or PR (destructive) |
  394. | `delete_issue_time_entry` | Delete a single tracked time entry by ID |
  395. | `start_issue_stopwatch` | Start a stopwatch on an issue or PR |
  396. | `stop_issue_stopwatch` | Stop a running stopwatch and record the elapsed time |
  397. | `cancel_issue_stopwatch` | Cancel a running stopwatch without recording |
  398. | `list_my_stopwatches` | List currently running stopwatches |
  399. | **Attachments** | |
  400. | `list_issue_attachments` | List attachments on an issue or PR |
  401. | `get_issue_attachment` | Get metadata for a single issue/PR attachment |
  402. | `download_issue_attachment` | Download an issue/PR attachment (inline if < 1 MiB; metadata + URL otherwise) |
  403. | `create_issue_attachment` | Upload a new attachment to an issue or PR (base64 content or a file path on the MCP host) |
  404. | `edit_issue_attachment` | Rename an issue/PR attachment |
  405. | `delete_issue_attachment` | Delete an issue/PR attachment |
  406. | `list_comment_attachments` | List attachments on an issue/PR comment |
  407. | `get_comment_attachment` | Get metadata for a single comment attachment |
  408. | `download_comment_attachment` | Download a comment attachment (inline if < 1 MiB; metadata + URL otherwise) |
  409. | `create_comment_attachment` | Upload a new attachment to an issue/PR comment (base64 content or a file path on the MCP host) |
  410. | `edit_comment_attachment` | Rename a comment attachment |
  411. | `delete_comment_attachment` | Delete a comment attachment |
  412. | **Releases** | |
  413. | `list_releases` | List releases for a repository (page/limit + client-side `state` filter: all/draft/prerelease/published) |
  414. | `get_release_by_id` | Get a release by numeric ID |
  415. | `get_release_by_tag` | Get a release by tag name |
  416. | `get_latest_release` | Get the latest non-draft, non-prerelease release |
  417. | `create_release` | Create a new release (pass `target_commitish` to also create the tag) |
  418. | `edit_release` | Update fields of an existing release (only supplied fields are sent) |
  419. | `delete_release` | Delete a release by numeric ID — destructive |
  420. | `delete_release_by_tag` | Delete a release by tag name — destructive, verify tag |
  421. | `list_release_attachments` | List attachments on a release (response fetched in full, sliced client-side) |
  422. | `get_release_attachment` | Get metadata for a single release attachment |
  423. | `download_release_attachment` | Download a release attachment (inline if < 1 MiB; metadata + URL otherwise) |
  424. | `create_release_attachment` | Upload a new attachment to a release (base64 content or a file path on the MCP host) |
  425. | `edit_release_attachment` | Rename a release attachment |
  426. | `delete_release_attachment` | Delete a release attachment — destructive |
  427. | **Wiki** | |
  428. | `list_wiki_pages` | List pages using `page`/`limit`; returns `has_next` and, when Forgejo reports `X-Total-Count`, `total_count`. `total_count` counts upstream's raw wiki tree entries, so it can exceed the number of pages listed on a wiki with subdirectories — an upper bound, not an exact total. |
  429. | `get_wiki_page` | Read decoded Markdown; optional `start_line`/`end_line`, always returns `total_lines`. |
  430. | `get_wiki_revisions` | List revision history using `page`/`limit`; returns `has_next` and `total_count`, the page's total revision count as reported in the response body. |
  431. | `create_wiki_page` | Create a page and return its server-normalized `page_name`; slash-separated titles are a flat subpage naming convention (no hierarchy and no automatic parent page), and an existing title is overwritten. |
  432. | `update_wiki_page` | Update content/title by normalized `page_name`; last writer wins. |
  433. | `delete_wiki_page` | Delete a page by normalized `page_name`. |
  434. | **Server** | |
  435. | `get_forgejo_mcp_server_version` | Get the MCP server version |
  436. ## Resources
  437. MCP resource templates expose Forgejo entities as URI-addressable resources using the `forgejo://` scheme. The URI scheme is instance-portable — the same URI form works against any Forgejo instance — and does not collide with Forgejo web links. Clients that support `resources/templates/list` and `resources/read` (Claude Code, Claude Desktop, Codex, Cursor) can resolve these URIs directly. Clients without resource-template support continue to use the tools above — no functionality is removed.
  438. Resources do NOT replace any MCP tool — every existing list/get tool stays available; resources are an additive, URI-addressable read surface intended for auto-resolution from LLM context and for content-addressable caching of immutable entities like commits.
  439. Resources that embed a list (issue, pr) cap the embedded array at 30 items. When truncated, the JSON payload includes a sentinel naming the corresponding `list_*` tool the caller should invoke for the full list.
  440. **When to use resources vs tools:** prefer a resource when you have a specific sha or index in hand; prefer a tool when listing or searching.
  441. | URI Template | Entity | Notes |
  442. |---|---|---|
  443. | `forgejo://owner/{owner}` | application/json | User or org profile addressed by login; resolves user first, falls back to org. |
  444. | `forgejo://repo/{owner}/{repo}` | application/json | Repository overview: identity + counts, no embedded lists. |
  445. | `forgejo://repo/{owner}/{repo}/commit/{sha}` | Commit metadata | Immutable per sha. Returns JSON + markdown sidecar. sha must be 40 hex chars. |
  446. | `forgejo://repo/{owner}/{repo}/commit/{sha}/status` | application/json | Combined CI status for a sha: aggregate state + bounded per-context statuses (cap 30, sentinel names list tool `get_commit_statuses`). |
  447. | `forgejo://repo/{owner}/{repo}/issue/{index}` | application/json (+ text/markdown sidecar) | Issue metadata + rendered body + bounded recent comments (cap 30, sentinel names `list_issue_comments`). |
  448. | `forgejo://repo/{owner}/{repo}/issues{?state,labels,page,limit}` | application/json | Bounded list of issues as rows — index, title, state, author, labels, assignees, milestone, comment count, timestamps, due date — and **no bodies**. `state` ∈ {open, closed, all} (default `open`); `labels` comma-separated; cap 30, sentinel names `list_repo_issues`. Read the single-issue resource for a body. |
  449. | `forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id}` | application/json (+ text/markdown sidecar) | Single comment by id; kind ∈ {issue, pr}. |
  450. | `forgejo://repo/{owner}/{repo}/{kind}/{index}/comments{?page,limit}` | application/json | Bounded comment thread with **full bodies** (the single-issue resource excerpts them at 200 chars); kind ∈ {issue, pr}; cap 30, sentinel names `list_issue_comments`. |
  451. | `forgejo://repo/{owner}/{repo}/pr/{index}` | application/json (+ text/markdown sidecar) | PR metadata, head/base refs, mergeability, bounded recent comments (cap 30, sentinel `list_issue_comments`) and reviews (cap 30, sentinel `list_pull_reviews`). |
  452. | `forgejo://repo/{owner}/{repo}/branch_protections` | application/json | Bounded list of branch protection rules. |
  453. | `forgejo://repo/{owner}/{repo}/branch_protection/{rule}` | application/json | Single branch protection rule. Rule names are branch patterns, so encode a literal `/` as `%2F` and spaces as `%20` (`release%2Fv1`); a raw `/` does not resolve. |
  454. | `forgejo://repo/{owner}/{repo}/hooks` | application/json | Bounded list of repository webhooks (cap 30, sentinel names `list_repo_hooks`). The secret is never returned. |
  455. | `forgejo://repo/{owner}/{repo}/hook/{id}` | application/json | Single repository webhook by id. The secret is never returned. |
  456. | `forgejo://repo/{owner}/{repo}/label/{id}` | application/json | Single repository label by numeric id. |
  457. | `forgejo://repo/{owner}/{repo}/labels{?page,limit}` | application/json | Bounded list of repository labels (cap 30, sentinel names `list_repo_labels`). |
  458. | `forgejo://org/{org}/labels{?page,limit}` | application/json | Bounded list of organization-level labels (cap 30, sentinel names `list_org_labels`). |
  459. | `forgejo://repo/{owner}/{repo}/wiki/{pageName}` | application/json (+ text/markdown sidecar) | Wiki page with bounded revisions and Markdown capped at 1 MiB. Use the returned normalized `page_name`; encode a literal `/` as `%2F` and spaces as `%20` in the URI (do not double-encode an already normalized name). |
  460. Slash-separated titles such as `Guides/Setup` are useful as a subpage naming convention,
  461. but Forgejo stores the pages in a flat list: it neither creates `Guides` automatically nor
  462. records a parent-child relationship. Create the parent separately when readers need it, and
  463. always address subsequent calls with the normalized `page_name` returned by create or list.
  464. The wiki REST behavior documented here was live-tested against Forgejo
  465. `15.0.4+gitea-1.22.0`; the complete MCP demo was replayed successfully against
  466. `16.0.0+gitea-1.22.0`. This is the tested range, not a guarantee for every intermediate
  467. or differently proxied deployment.
  468. ### Client Compatibility
  469. | Client | `resources/templates/list` | `resources/read` |
  470. |---|---|---|
  471. | Claude Code | supported | supported |
  472. | Claude Desktop | supported | supported |
  473. | Codex | supported | supported |
  474. | Cursor (current) | supported | supported |
  475. | Older / minimal clients | tools only | tools only |
  476. ## Demos
  477. End-to-end, copy-pasteable walkthroughs of the tools above — grouped by
  478. topic (labels, attachments, time tracking, notifications, orgs, bounded
  479. I/O code review, transport) — live in [demos/](demos/README.md). Each
  480. demo pairs real `./forgejo-mcp --cli` invocations with the output they
  481. produced against `codeberg.org`.
  482. ## CLI Mode
  483. 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.
  484. ```bash
  485. # List all available tools (grouped by domain)
  486. forgejo-mcp --cli list
  487. # Invoke a tool with JSON arguments
  488. forgejo-mcp --cli get_issue_by_index --args '{"owner":"goern","repo":"forgejo-mcp","index":1}'
  489. # Pipe JSON arguments via stdin
  490. echo '{"owner":"goern","repo":"forgejo-mcp"}' | forgejo-mcp --cli list_repo_issues
  491. # List recent workflow runs (text output)
  492. forgejo-mcp --cli list_workflow_runs \
  493. --args '{"owner":"goern","repo":"forgejo-mcp"}' \
  494. --output=text
  495. # List only failed runs
  496. forgejo-mcp --cli list_workflow_runs \
  497. --args '{"owner":"goern","repo":"forgejo-mcp","status":"failure"}' \
  498. --output=text
  499. # Run-scoped tools (list_action_run_jobs, cancel_workflow_run, ...) take the
  500. # database run ID printed by list_workflow_runs (e.g. #2671), not the per-repo run
  501. # number in the web URL (.../actions/runs/222). To map a web-URL number to a
  502. # run ID, add "run_number":222 to the list_workflow_runs args.
  503. # List jobs and inspect the tail of a failed job (Forgejo v16+)
  504. forgejo-mcp --cli list_action_run_jobs \
  505. --args '{"owner":"goern","repo":"forgejo-mcp","run_id":123}' \
  506. --output=text
  507. forgejo-mcp --cli get_action_job_logs \
  508. --args '{"owner":"goern","repo":"forgejo-mcp","job_id":456,"max_bytes":32768}' \
  509. --output=text
  510. # Forgejo's run-wide ZIP log endpoint has no Range support. Enumerate jobs and
  511. # fetch their bounded plaintext logs instead.
  512. # List artifacts of a run, then read one artifact's metadata (no zip download, Forgejo v16+)
  513. forgejo-mcp --cli list_action_run_artifacts \
  514. --args '{"owner":"goern","repo":"forgejo-mcp","run_id":123,"limit":30}' \
  515. --output=text
  516. forgejo-mcp --cli get_action_artifact \
  517. --args '{"owner":"goern","repo":"forgejo-mcp","artifact_id":789}' \
  518. --output=text
  519. # List package versions for an owner, then inspect one version's files
  520. forgejo-mcp --cli list_packages \
  521. --args '{"owner":"OWNER","type":"container","limit":30}' \
  522. --output=text
  523. forgejo-mcp --cli get_package \
  524. --args '{"owner":"OWNER","type":"container","name":"app","version":"1.0.0"}' \
  525. --output=text
  526. forgejo-mcp --cli list_package_files \
  527. --args '{"owner":"OWNER","type":"container","name":"app","version":"1.0.0"}' \
  528. --output=text
  529. # delete_package removes one version. Do not invoke it against a registry you do not own.
  530. # cancel_workflow_run and delete_workflow_run need Forgejo v16+.
  531. # cancel_workflow_run is 204 even when the run already finished.
  532. # delete_workflow_run only succeeds for a completed run; a live run is an error.
  533. # Show a tool's parameters
  534. forgejo-mcp --cli create_issue --help
  535. # Control output format (json or text)
  536. forgejo-mcp --cli list --output=json
  537. forgejo-mcp --cli get_my_user_info --args '{}' --output=text
  538. ```
  539. CLI mode requires the same `FORGEJO_URL` and `FORGEJO_ACCESS_TOKEN` configuration as MCP server mode. Tool results are written as JSON to stdout by default; errors go to stderr with a non-zero exit code.
  540. ## Configuration Options
  541. You can configure the server using command-line arguments or environment variables:
  542. | CLI Argument | Environment Variable | Description |
  543. |--------------|---------------------|-------------|
  544. | `--url` | `FORGEJO_URL` | Your Forgejo instance URL |
  545. | `--token` | `FORGEJO_ACCESS_TOKEN` | Your personal access token |
  546. | `--debug` | `FORGEJO_DEBUG` | Enable debug mode |
  547. | `--transport` | - | Transport mode: `stdio`, `sse`, or `http` |
  548. | `--sse-port` | - | Port for SSE mode (default: 8080) |
  549. | `--http-port` | - | Port for streamable HTTP mode (default: 8080) |
  550. | `--host` | `FORGEJO_MCP_HOST` | Address the `sse` and `http` transports bind to (default: `localhost`, reachable from this machine only, binding both `127.0.0.1` and `::1`; pass one of those addresses to bind that family alone) |
  551. | `--allowed-hosts` | `FORGEJO_MCP_ALLOWED_HOSTS` | Comma-separated `Host` names this server answers to; required when `--host` is not loopback |
  552. | `--allowed-origins` | `FORGEJO_MCP_ALLOWED_ORIGINS` | Comma-separated web origins allowed to send an `Origin` header, as full origins (`https://console.example.org`). Empty by default |
  553. | `--allow-operator-token-fallback` | `FORGEJO_MCP_ALLOW_OPERATOR_TOKEN_FALLBACK` | On `sse`/`http`, serve requests with no `Authorization` header using this server's own token. Off by default |
  554. | `--heartbeat` | `FORGEJO_MCP_HEARTBEAT` | Interval at which `sse`/`http` write a JSON-RPC `ping` into the notification stream, so clients and proxies with an idle timeout keep it (default: `30s`; `0` sends none) |
  555. | `--auth-mode` | `FORGEJO_MCP_AUTH_MODE` | `passthrough` (default) or `resource-server`; see [Remote operation as an OAuth resource server](#remote-operation-as-an-oauth-resource-server) |
  556. | `--authorization-server` | `FORGEJO_MCP_AUTHORIZATION_SERVER` | `resource-server` mode: issuer URL of the OpenID Connect provider, compared byte for byte |
  557. | `--resource` | `FORGEJO_MCP_RESOURCE` | `resource-server` mode: canonical URI of the MCP endpoint, for example `https://mcp.example.org/mcp`; its path must be `/mcp` |
  558. | `--resource-audience` | `FORGEJO_MCP_RESOURCE_AUDIENCE` | `resource-server` mode: value an access token's `aud` must contain (default: the value of `--resource`) |
  559. | `--scopes-supported` | `FORGEJO_MCP_SCOPES_SUPPORTED` | `resource-server` mode: space-separated scopes published in the metadata and the `401` challenge (default: none published) |
  560. | `--forgejo-audience-claim` | `FORGEJO_MCP_FORGEJO_AUDIENCE_CLAIM` | `resource-server` mode: access-token claim holding the audience of the caller's Forgejo Authorized Integration (default: `forgejo_aud`) |
  561. | `--forgejo-jwt-issuer` | `FORGEJO_MCP_FORGEJO_JWT_ISSUER` | `resource-server` mode: issuer URL under which the server signs JWTs for Forgejo, for example `https://mcp.example.org/issuer`; https, without a trailing slash |
  562. | `--forgejo-jwt-signing-key-file` | `FORGEJO_MCP_FORGEJO_JWT_SIGNING_KEY_FILE` | `resource-server` mode: PEM private key that signs the JWTs for Forgejo (EC P-256 or P-384, Ed25519, or RSA of at least 2048 bits) |
  563. | `--forgejo-jwt-published-key-files` | `FORGEJO_MCP_FORGEJO_JWT_PUBLISHED_KEY_FILES` | `resource-server` mode: comma-separated PEM keys published next to the signing key, for key rotation |
  564. | `--cli` | - | Enter CLI mode for direct tool invocation |
  565. | `--user-agent` | `FORGEJO_USER_AGENT` | HTTP User-Agent header (default: `forgejo-mcp/<version>`) |
  566. | - | `FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD` | Allow `file_path` attachment uploads to read the host filesystem (`1`/`true`/`yes`/`on`; off by default) |
  567. | - | `FORGEJO_MCP_UPLOAD_ROOT` | Confine `file_path` uploads to this directory (default: anywhere the process can read) |
  568. Command-line arguments take priority over environment variables.
  569. The `resource-server` settings are refused in `passthrough` mode, so a configuration that sets them but forgets `--auth-mode resource-server` does not start.
  570. ### Uploading attachments from the host filesystem
  571. `create_issue_attachment`, `create_comment_attachment`, and
  572. `create_release_attachment` accept either base64 `content` or a `file_path` on
  573. the machine running `forgejo-mcp`. The path form avoids base64-expanding a large
  574. release artifact through the MCP transport.
  575. It is **off by default**, because it hands whatever drives the MCP client the
  576. ability to read any file the server process can read — a prompt-injected agent
  577. could upload `~/.ssh/id_ed25519` as a public release asset. Turn it on
  578. deliberately, and prefer confining it:
  579. ```bash
  580. export FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD=1
  581. export FORGEJO_MCP_UPLOAD_ROOT=/home/you/build/dist # optional but recommended
  582. ```
  583. With `FORGEJO_MCP_UPLOAD_ROOT` set, a path that resolves outside that directory
  584. — by being absolute, by `..`, or through a symlink — is rejected before anything
  585. is read. Base64 `content` uploads are unaffected by either variable.
  586. ## Verifying Releases
  587. Release archives are accompanied by a `checksums.txt` file and an optional
  588. `checksums.txt.sig` produced by [cosign](https://github.com/sigstore/cosign)
  589. with the project's release keypair. Verifying both files lets you confirm
  590. that the binary you downloaded was built by the project's release pipeline
  591. and has not been tampered with in transit.
  592. > **Heads up:** cosign signing was introduced mid-2026. Tags released
  593. > before signing was wired up ship without a `.sig` file — verification
  594. > applies from `v2.23.x` onward only, and only when the
  595. > `COSIGN_PRIVATE_KEY` secret was configured at release time.
  596. ### 1. Install cosign
  597. Follow the upstream
  598. [cosign installation guide](https://docs.sigstore.dev/cosign/system_config/installation/)
  599. for your platform. Quick paths:
  600. ```bash
  601. # Linux/macOS — pinned binary
  602. COSIGN_VERSION=v2.4.1
  603. curl -sSfL -o /usr/local/bin/cosign \
  604. "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64"
  605. chmod +x /usr/local/bin/cosign
  606. # macOS via Homebrew
  607. brew install cosign
  608. # Arch Linux
  609. sudo pacman -S cosign
  610. ```
  611. Confirm:
  612. ```bash
  613. cosign version
  614. ```
  615. ### 2. Fetch the public key
  616. The normative source for the cosign public key is the
  617. [`op1st-emea-b4mad`](https://codeberg.org/operate-first/op1st-emea-b4mad)
  618. GitOps repo — same source of truth that provisions the
  619. `cosign-signing-key-artifacts` Secret in the `op1st-pipelines` namespace
  620. where the release pipeline runs. This is the **artifact-signing** key that
  621. signs release blobs (`checksums.txt.sig`); it is distinct from the
  622. **image-signing** key `cosign-signing-key-images.pub` used in §5–§6 below.
  623. Two ways to fetch it:
  624. **Branch-tip (live, follows future key rotations):**
  625. ```bash
  626. curl -sSfL -o cosign.pub \
  627. https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub
  628. ```
  629. **Commit-pinned (tamper-evident, recommended for CI/scripts):**
  630. ```bash
  631. curl -sSfL -o cosign.pub \
  632. https://codeberg.org/operate-first/op1st-emea-b4mad/raw/commit/cd3715fa8283a2069a2e3e299744a7b55b1b0260/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub
  633. ```
  634. The commit-pinned permalink hashes its content into the URL — if anyone
  635. ever rewrites the file at that commit, your download fails or mismatches.
  636. Pin to the latest commit that you trust before adopting the key in
  637. automation.
  638. ### 3. Download the release artifacts
  639. Pick the tag you installed (e.g. `v3.1.0`) and grab the checksum file,
  640. its signature, and the binary archive:
  641. ```bash
  642. TAG=v3.1.0
  643. VERSION="${TAG#v}"
  644. BASE="https://git.b4mad.industries/agentic-forges/forgejo-mcp/releases/download/${TAG}"
  645. curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt"
  646. curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt.sig"
  647. curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_linux_amd64.tar.gz" # adjust os/arch
  648. ```
  649. ### 4. Verify the signature, then the checksum
  650. Cosign verifies that `checksums.txt` was signed by the holder of the
  651. private key matching `cosign.pub`. Once the checksum file is trusted, a
  652. plain `sha256sum -c` check confirms the archive's integrity.
  653. ```bash
  654. # Verify checksums.txt against the signature.
  655. cosign verify-blob \
  656. --key cosign.pub \
  657. --signature "forgejo-mcp_${VERSION}_checksums.txt.sig" \
  658. "forgejo-mcp_${VERSION}_checksums.txt"
  659. # Expected: "Verified OK"
  660. # Verify the downloaded archive against the (now-trusted) checksums.
  661. sha256sum --ignore-missing -c "forgejo-mcp_${VERSION}_checksums.txt"
  662. # Expected: "<archive>: OK"
  663. ```
  664. The checksum chain transitively covers the SBOMs and other per-archive
  665. assets — verifying `checksums.txt` once is sufficient for everything
  666. listed inside it.
  667. ### 5. Verify SLSA provenance for the release-tools image
  668. The release-tools container image (used internally by the Tekton release
  669. pipeline) carries SLSA v1.0 provenance generated by [Tekton
  670. Chains](https://tekton.dev/docs/chains/). This attestation binds the image
  671. digest to the exact PipelineRun, git commit, and builder identity that
  672. produced it — providing supply-chain provenance beyond what the cosign
  673. signature alone can attest.
  674. Fetch the `cosign-signing-key-images` public key (a separate key from the
  675. artifact-signing key above):
  676. ```bash
  677. curl -sSfL -o cosign-images.pub \
  678. https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-images.pub
  679. ```
  680. Verify the attestation against a specific image tag:
  681. ```bash
  682. IMAGE_TAG=v1.0.0 # substitute the release-tools tag you want to verify
  683. cosign verify-attestation \
  684. --type slsaprovenance \
  685. --key cosign-images.pub \
  686. "codeberg.org/operate-first/release-tools:${IMAGE_TAG}" \
  687. | jq .
  688. ```
  689. A successful run prints the decoded in-toto statement (JSON). Check that
  690. `predicate.buildDefinition.externalParameters.runSpec.params` references the
  691. expected git revision, and `predicate.runDetails.builder.id` shows the
  692. Tekton Chains builder.
  693. > **Note:** SLSA provenance attestations are available from releases built
  694. > after forgejo-mcp-46j (Tekton Chains support) landed. Earlier image tags
  695. > carry only the cosign signature; they have no `verify-attestation` payload.
  696. ### 6. Verify the container image
  697. The `git.b4mad.industries/agentic-forges/forgejo-mcp` application image ([Option D](#1-install))
  698. is signed by the same `cosign-signing-key-images` key as the release-tools
  699. image, carries an attached CycloneDX SBOM, and gets SLSA v1.0 provenance from
  700. Tekton Chains. Reuse the `cosign-images.pub` key fetched above.
  701. Verify the signature:
  702. ```bash
  703. IMAGE_TAG=v3.1.0 # substitute the release you are pulling
  704. cosign verify \
  705. --key cosign-images.pub \
  706. "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  707. | jq .
  708. ```
  709. Verify the SLSA provenance attestation:
  710. ```bash
  711. cosign verify-attestation \
  712. --type slsaprovenance \
  713. --key cosign-images.pub \
  714. "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  715. | jq .
  716. ```
  717. Verify and download the signed CycloneDX SBOM attestation:
  718. ```bash
  719. cosign verify-attestation \
  720. --type cyclonedx \
  721. --key cosign-images.pub \
  722. "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  723. | jq -r '.payload | @base64d | fromjson | .predicate' > forgejo-mcp.cdx.json
  724. ```
  725. > The SBOM is now a **signed** in-toto attestation (`cosign attest`), not an
  726. > unsigned `attach sbom` artifact. `cosign download sbom` no longer applies.
  727. Because the publish pipeline pushes by digest and only promotes the
  728. `vX.Y.Z` / `latest` tags *after* signing and SBOM attachment succeed, any tag
  729. you can pull is guaranteed to be signed.
  730. ### Troubleshooting verification
  731. - **`Error: no matching signatures`** — the `.sig` file is from a
  732. different release, or `cosign.pub` is the wrong key. Re-download both
  733. from the same tag.
  734. - **`Error: cannot read file: checksums.txt.sig`** — release predates
  735. cosign signing, or signing was skipped that run because the secret was
  736. unset. Fall back to the checksum-only check (`sha256sum -c`), which
  737. still detects in-transit corruption but not tampering.
  738. - **Mismatch between `cosign.pub` and the signature** — confirm you
  739. fetched the public key from a commit that includes the key in use at
  740. the time of the release. If in doubt, fetch from `branch/main`.
  741. ## Troubleshooting
  742. **Enable debug mode** to see detailed logs:
  743. ```bash
  744. forgejo-mcp --transport sse --url <url> --token <token> --debug
  745. ```
  746. Or set the environment variable:
  747. ```bash
  748. export FORGEJO_DEBUG=true
  749. ```
  750. **Custom User-Agent**: If your Forgejo instance or proxy blocks the default `go-http-client` user agent, set a custom one:
  751. ```bash
  752. # Via environment variable
  753. export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"
  754. # Or via CLI flag
  755. forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url <url> --token <token>
  756. ```
  757. ## Getting Help
  758. - [Report issues](https://git.b4mad.industries/agentic-forges/forgejo-mcp/issues) — bugs, questions, feature requests
  759. - **Found a security problem?** Do not use the issue tracker. See [SECURITY.md](SECURITY.md) for how to report it privately.
  760. - [View source code](https://git.b4mad.industries/agentic-forges/forgejo-mcp)
  761. - [Chat on Matrix](https://matrix.to/#/%23forgejo-mcp:b4mad.net) — `#forgejo-mcp:b4mad.net`
  762. This repository is also mirrored on [Radicle](https://radicle.xyz/) — a peer-to-peer code collaboration network. Clone via:
  763. ```bash
  764. rad clone rad:z4PdPpsH9iJQcWfqTbxpFcWaZ9zPL
  765. ```
  766. ## For Developers
  767. See [DEVELOPER.md](DEVELOPER.md) for build instructions, architecture overview, and contribution guidelines.
  768. ## Known Issues
  769. - **Installing from the old Codeberg module path** — `go install
  770. codeberg.org/goern/forgejo-mcp/v2@latest` still resolves, against the
  771. read-only mirror, but that mirror lags behind the current release. Use
  772. `git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest` instead.
  773. This entry used to say that the new path was not installable until a
  774. release carried the renamed `go.mod`. That release has happened —
  775. `v3.0.0` onwards declare `module git.b4mad.industries/agentic-forges/forgejo-mcp/v3`
  776. — so the new path installs normally. The earlier `replace`-directive
  777. blocker ([#67](https://git.b4mad.industries/agentic-forges/forgejo-mcp/issues/67))
  778. is also gone; `go.mod` no longer contains one.
  779. ## Contributors
  780. forgejo-mcp is shaped by everyone who files issues, writes code, reviews PRs, and pushes the project forward. Thank you all. 🙏
  781. ### Code contributors
  782. | Contributor | Highlights |
  783. |-------------|------------|
  784. | [goern](https://codeberg.org/goern) (Christoph Görn) | Project creator and maintainer |
  785. | Ronmi Ren | Co-creator; SSE/HTTP transport, issue blocking, CI/CD improvements, logo, Glama spec |
  786. | [twstagg](https://codeberg.org/twstagg) (Tristin Stagg) | User agent configuration support (PR #89) |
  787. | [mattdm](https://codeberg.org/mattdm) (Matthew Miller) | Logging improvements, FORGEJO_* migration, README, URL refactor |
  788. | [byteflavour](https://codeberg.org/byteflavour) | `check_notifications` + full notification management API (PR #84, #86); stateless per-request auth for HTTP/SSE transports (PR #138); NixOS installation docs (PR #146); network transport hardening — loopback-by-default bind, `Host`/`Origin` checks, per-request credential (PR #545, landed as #573; #586, #585, #589); **OAuth resource-server mode** — inbound JWT validation and outbound Forgejo 16 Authorized Integration signing, with operator and user guides and 40 anchored demo scenarios (PR #584, researched in #582); dev-env `FORGEJO_MCP_EXEC` (PR #580); feature requests #80, #85 |
  789. | [jesterret](https://codeberg.org/jesterret) | Pull request reviews and comments support (PR #51) |
  790. | [appleboy](https://codeberg.org/appleboy) | Custom SSE port support, bug fixes |
  791. | [ignasgil](https://codeberg.org/ignasgil) | `remove_issue_labels` tool (PR #96) |
  792. | [dmikushin](https://codeberg.org/dmikushin) (Dmitry Mikushin) | Fix string-encoded number parameter parsing from MCP clients (PR #93) |
  793. | [jiriks74](https://codeberg.org/jiriks74) | mcp-go v0.44.0 dependency update (PR #90) |
  794. | [th](https://codeberg.org/th) (Tomi Haapaniemi) | `update_pull_request` tool |
  795. | [hiifong](https://codeberg.org/hiifong) | Early bug fixes and updates |
  796. | [Lunny Xiao](https://codeberg.org/lunny) | Early contributions |
  797. | [techknowlogick](https://codeberg.org/techknowlogick) | Early contributions |
  798. | [yp05327](https://codeberg.org/yp05327) | Early contributions |
  799. | [mw75](https://codeberg.org/mw75) | Owner/org support for repo creation (PR #18) |
  800. | [Dax Kelson](https://codeberg.org/dkelson) | Issue comment management (PR #34) |
  801. | [Guruprasad Kulkarni](https://codeberg.org/comdotlinux) | Arch Linux AUR installation docs (PR #69) |
  802. | [Mario Wolff](https://codeberg.org/mariowolff) | Contributions |
  803. | [Massimo Fraschetti](https://codeberg.org/fraschetti) | Contributions |
  804. | [synath](https://codeberg.org/synath) (David Paul Turley) | Repository-scoped token support via `ServerVersion` probe (PR #112); merge status-code check (PR #113); Claude Desktop Extension (.mcpb) packaging (PR #118, #123); issue `due_date` + server-side sort (PR #483); bounded issue-list and comment-thread resources (PR #487); `total_count` on paginated envelopes from `X-Total-Count` (PR #507); `create_*_attachment` timeout hardening (PR #534, #536); cross-repo issue dependencies (PR #535) |
  805. | [BrilliantKahn](https://codeberg.org/BrilliantKahn) | `get_file_content` plain-text default (PR #116); `list_repo_contents` and `get_repo_tree` tools (PR #117). **First-ever open source contribution** — welcome aboard! 🎉 |
  806. | [nesvet](https://git.b4mad.industries/nesvet) (Eugene Nesvetaev) | `get_repo`/`edit_repo` (PR #527); repository topic tools (PR #528); Actions run cancel/delete and run artifacts (PR #533); `get_commit_statuses` (PR #542); package list/get/delete/files tools (PR #543); label names accepted on issue create, assignment and replace (PR #591); `exclusive` and `is_archived` on label create, edit and read (PR #592) |
  807. | [pisco](https://git.b4mad.industries/pisco) (Marco Pisco) | `file_path` uploads for issue, comment, and release attachments, with streaming multipart so large release assets no longer round-trip through base64 (PR #481) |
  808. | [paulgit](https://git.b4mad.industries/paulgit) (Paul Git) | Accurate MCP annotations and titles declared on every tool, with the classification rubric in DEVELOPER.md (PR #633, replacing #602) |
  809. | [derliebemarcus](https://git.b4mad.industries/derliebemarcus) (Marcus Pauli) | `change_files` atomic multi-file commits and binary-safe `content_base64` on `create_file`/`update_file` (PR #628); `apply_diff_patch` native diff-patch writes (PR #629) |
  810. | [MaherMakerHallerErne](https://git.b4mad.industries/MaherMakerHallerErne) (Maher Al Sairawan) | Issue dependency tools — `list_issue_dependencies`, `list_issue_dependents`, `add_issue_dependency`, `remove_issue_dependency` — with the correct Forgejo API contract (PR #335) |
  811. | [woozar](https://git.b4mad.industries/woozar) (Johannes Herrmann) | Wiki support over the direct REST API — page list/get/create/update/delete and revisions, with hardened contracts and pagination (PR #379) |
  812. | [dismantl](https://git.b4mad.industries/dismantl) (Dan Staples) | Bounded Forgejo v16+ workflow job logs — `list_action_run_jobs`, `get_action_job_logs` (PR #378) |
  813. | [matheusalves96](https://git.b4mad.industries/matheusalves96) (Matheus Alves) | Repository and organization Actions secrets tools — list, create-or-update, delete (PR #605) |
  814. ### Community contributors
  815. Issue reporters and discussion participants who shaped the direction of the project:
  816. | Contributor | Contributions |
  817. |-------------|--------------|
  818. | [byteflavour](https://codeberg.org/byteflavour) | Filed #80 (milestone/label discovery), #85 (notification API proposal); active reviewer in discussions |
  819. | [choucavalier](https://codeberg.org/choucavalier) | Filed #82 (fix skill), #70 (macOS arm64 releases), #62 (binary releases & mise support) |
  820. | [MalcolmMielle](https://codeberg.org/MalcolmMielle) | Filed #59 (PR review tools — since implemented) |
  821. | [redbeard](https://codeberg.org/redbeard) | Filed #60 (Actions support — since implemented) |
  822. | [c6sepl6p](https://codeberg.org/c6sepl6p) | Filed #72 (base64 encoding), #54 (merge pull request — since implemented) |
  823. | [malik](https://codeberg.org/malik) | Filed #73 (version flag), #47 (Nix build fix) |
  824. | [a2800276](https://codeberg.org/a2800276) | Filed #74 (OpenAI compatibility) |
  825. | [simenandre](https://codeberg.org/simenandre) | Filed #49 (go install support) |
  826. | [BasdP](https://codeberg.org/BasdP) | Filed #42 (Projects support) |
  827. | [BoBeR182](https://codeberg.org/BoBeR182) | Filed #32 (wiki support) |
  828. | [ignasgil](https://codeberg.org/ignasgil) | Filed #95 (`remove_issue_labels` feature request) |
  829. | [Vokuar](https://codeberg.org/Vokuar) | Filed #99 (streamable HTTP transport support) |
  830. | [janbaer](https://codeberg.org/janbaer) | Filed #98 (reply to review comment) |
  831. | [fraschm98](https://codeberg.org/fraschm98) | Early issue reports |
  832. | [heathen711](https://codeberg.org/heathen711) | Filed #106 (issue/comment attachments — since implemented); shaped the 1 MiB inline cap + `browser_download_url` fall-through design |
  833. | [decarvalhoaa](https://git.b4mad.industries/decarvalhoaa) (Antonio De Carvalho) | Filed #593 (server-side response size cap) from a real context-window overflow behind Open WebUI, with the measurement that prompted the `list_repo_pull_requests` payload work in #596 |
  834. | [chris420](https://git.b4mad.industries/chris420) (Chris Oloff) | Filed #452 (org-wide issue search — since implemented as `search_issues`); design review on PR #458 that replaced the next-page probe with instance-ceiling enforcement, and caught the response envelope misreporting its own `limit` |
  835. ### Cyborg contributors
  836. This project also received contributions from AI coding agents — submitted as regular PRs, reviewed by humans:
  837. | Agent | Role | Contributions |
  838. |-------|------|---------------|
  839. | [brenner-axiom](https://codeberg.org/brenner-axiom) (b4-dev, B4arena) | AI dev agent | Organization management tools (PR #94); showboat demos (PR #97); `list_repo_milestones`, `list_repo_labels` tools (PR #83); race condition fix (PR #78); contributors docs (PR #87, #88); filed #76; code reviews |
  840. | opencode | AI dev agent | Pull request reviews and comments support (PR #51) |
  841. | claude-code | AI dev agent | `get_file_content` plain-text default and `list_repo_contents`/`get_repo_tree` tools, paired with [BrilliantKahn](https://codeberg.org/BrilliantKahn) (PR #116, #117) |
  842. | b4mad-release-agent | Release automation | Automated changelog and release tagging |
  843. | the #B4mad Renovate bot | Dependency updates | Automated dependency upgrades |
  844. Want to contribute? Open an issue or pull request — all are welcome.
  845. ## License
  846. This project is open source. See the repository for license details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.