Forgejo MCP Server

- Manage issues, pull requests, and comments
- Browse, create, update, and delete files
- List and manage branches and branch protection rules
- Trigger and inspect Actions workflow runs
- Track time on issues and manage stopwatches
- Handle issue/comment attachments (upload, download, delete)
- Support single‑tenant and multi‑tenant HTTP modes
- Multiple transport options: stdio, streamable HTTP, SSE

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.

Option D: Container image

A signed multi-stage OCI image is published on every release to
codeberg.org/goern/forgejo-mcp. Run the server without building from source:

```bash

| Tool | Description |
|------|-------------|
| User | |
| get_my_user_info | Get information about the authenticated user |
| check_notifications | Check and list user notifications |
| get_notification_thread | Get detailed info on a single notification thread |
| mark_notification_read | Mark a single notification thread as read |
| mark_all_notifications_read | Acknowledge all notifications |
| list_repo_notifications | Filter notifications scoped to a single repository |
| mark_repo_notifications_read | Mark all notifications in a specific repo as read |
| search_users | Search for users |
| Repositories | |
| list_my_repos | List all repositories you own |
| create_repo | Create a new repository |
| fork_repo | Fork a repository |
| search_repos | Search for repositories |
| Branches | |
| list_branches | List all branches in a repository |
| create_branch | Create a new branch |
| delete_branch | Delete a branch |
| Branch Protection | |
| 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. |
| get_branch_protection | Get a single rule by rule name |
| 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"). |
| edit_branch_protection | Edit a rule by rule name. Only fields you pass change; omitted fields are left unchanged. |
| delete_branch_protection | Delete a rule by rule name |
| Files | |
| 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). |
| create_file | Create a new file |
| update_file | Update an existing file |
| delete_file | Delete a file |
| Commits | |
| list_repo_commits | List commits in a repository |
| Issues | |
| list_repo_issues | List issues in a repository |
| get_issue_by_index | Get a specific issue |
| create_issue | Create a new issue |
| add_issue_labels | Add labels to an issue (requires numeric label IDs) |
| remove_issue_labels | Remove labels from an issue (requires numeric label IDs) |
| update_issue | Update an existing issue (requires numeric milestone ID) |
| issue_state_change | Open or close an issue |
| list_repo_milestones | List milestones with their IDs (use with update_issue) |
| 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"). |
| list_org_labels | List organization-level labels with their IDs (use with add_issue_labels, remove_issue_labels). |
| create_repo_label | Create a repository label (name, color as 6-digit hex, optional description). Returns numeric id for immediate use in add_issue_labels. |
| edit_repo_label | Edit a repository label (PATCH — only supplied fields change: name, color, description). |
| delete_repo_label | Delete a repository label. Refuses by default when the label is in use (reports count); set delete_mode=force to override. |
| get_repo_label | Get a single repository label by numeric id. |
| create_org_label | Create an organization-level label. Same fields as create_repo_label. |
| edit_org_label | Edit an organization-level label (PATCH semantics). |
| delete_org_label | Delete an organization-level label. In-use guard counts across visible org repos (best-effort); delete_mode=force overrides. |
| get_org_label | Get a single organization-level label by numeric id. |
| Comments | |
| list_issue_comments | List comments on an issue or PR |
| get_issue_comment | Get a specific comment |
| create_issue_comment | Add a comment to an issue or PR |
| edit_issue_comment | Edit a comment |
| delete_issue_comment | Delete a comment |
| Pull Requests | |
| list_repo_pull_requests | List pull requests in a repository |
| get_pull_request_by_index | Get a specific pull request |
| create_pull_request | Create a new pull request |
| update_pull_request | Update an existing pull request |
| list_pull_reviews | List reviews for a pull request |
| get_pull_review | Get a specific pull request review |
| list_pull_review_comments | List comments on a pull request review |
| 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. |
| 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). |
| merge_pull_request | Merge a pull request (style: merge/rebase/rebase-merge/squash; optional title/message/delete-branch/force-merge/wait-for-checks). |
| create_pull_review | Create a review on a pull request (state: APPROVED/REQUEST_CHANGES/COMMENT) with optional inline comments. |
| Actions | |
| dispatch_workflow | Trigger a workflow run via workflow_dispatch event |
| list_workflow_runs | List workflow runs with optional filtering by status, event, or SHA |
| get_workflow_run | Get details of a specific workflow run by ID |
| Organizations | |
| search_org_teams | Search for teams in an organization |
| Time Tracking | |
| list_issue_tracked_times | List tracked time entries on an issue or PR |
| list_repo_tracked_times | List tracked time entries across a repository |
| list_my_tracked_times | List your own tracked time entries |
| add_issue_time | Log time against an issue or PR (accepts seconds or duration like 15m) |
| reset_issue_time | Delete ALL tracked time entries on an issue or PR (destructive) |
| delete_issue_time_entry | Delete a single tracked time entry by ID |
| start_issue_stopwatch | Start a stopwatch on an issue or PR |
| stop_issue_stopwatch | Stop a running stopwatch and record the elapsed time |
| cancel_issue_stopwatch | Cancel a running stopwatch without recording |
| list_my_stopwatches | List currently running stopwatches |
| Attachments | |
| list_issue_attachments | List attachments on an issue or PR |
| get_issue_attachment | Get metadata for a single issue/PR attachment |
| download_issue_attachment | Download an issue/PR attachment (inline if < 1 MiB; metadata + URL otherwise) |
| create_issue_attachment | Upload a new attachment to an issue or PR (base64 content) |
| edit_issue_attachment | Rename an issue/PR attachment |
| delete_issue_attachment | Delete an issue/PR attachment |
| list_comment_attachments | List attachments on an issue/PR comment |
| get_comment_attachment | Get metadata for a single comment attachment |
| download_comment_attachment | Download a comment attachment (inline if < 1 MiB; metadata + URL otherwise) |
| create_comment_attachment | Upload a new attachment to an issue/PR comment (base64 content) |
| edit_comment_attachment | Rename a comment attachment |
| delete_comment_attachment | Delete a comment attachment |
| Releases | |
| list_releases | List releases for a repository (page/limit + client-side state filter: all/draft/prerelease/published) |
| get_release_by_id | Get a release by numeric ID |
| get_release_by_tag | Get a release by tag name |
| get_latest_release | Get the latest non-draft, non-prerelease release |
| create_release | Create a new release (pass target_commitish to also create the tag) |
| edit_release | Update fields of an existing release (only supplied fields are sent) |
| delete_release | Delete a release by numeric ID — destructive |
| delete_release_by_tag | Delete a release by tag name — destructive, verify tag |
| list_release_attachments | List attachments on a release (response fetched in full, sliced client-side) |
| get_release_attachment | Get metadata for a single release attachment |
| download_release_attachment | Download a release attachment (inline if < 1 MiB; metadata + URL otherwise) |
| create_release_attachment | Upload a new attachment to a release (base64 content) |
| edit_release_attachment | Rename a release attachment |
| delete_release_attachment | Delete a release attachment — destructive |
| Server | |
| get_forgejo_mcp_server_version | Get the MCP server version |