1  # Forgejo MCP Server
  2  
  3  Connect your AI assistant to Forgejo repositories. Manage issues, pull requests, files, and more through natural language.
  4  
  5  ## What It Does
  6  
  7  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.
  8  
  9  **Example commands you can use:**
 10  - "List all my repositories"
 11  - "Create an issue titled 'Bug in login page'"
 12  - "Show me open pull requests in my-org/my-repo"
 13  - "Get the contents of README.md from the main branch"
 14  - "Show me the latest Actions workflow runs in goern/forgejo-mcp"
 15  
 16  ## Quick Start
 17  
 18  ### 1. Install
 19  
 20  **Option A: Using Go (Recommended)**
 21  
 22  ```bash
 23  git clone https://codeberg.org/goern/forgejo-mcp.git
 24  cd forgejo-mcp
 25  go install .
 26  ```
 27  
 28  Ensure `$GOPATH/bin` (typically `~/go/bin`) is in your PATH.
 29  
 30  > **Note:** `go install codeberg.org/goern/forgejo-mcp/v2@latest` does not work currently. See [Known Issues](#known-issues).
 31  
 32  **Option B: Download Binary**
 33  
 34  Download the latest release from the [releases page](https://codeberg.org/goern/forgejo-mcp/releases).
 35  
 36  For Arch Linux, use your favorite AUR helper:
 37  
 38  ```bash
 39  yay -S forgejo-mcp      # builds from source
 40  yay -S forgejo-mcp-bin  # uses pre-built binary
 41  ```
 42  
 43  ### 2. Get Your Access Token
 44  
 45  1. Log into your Forgejo instance
 46  2. Go to **Settings** → **Applications** → **Access Tokens**
 47  3. Create a new token with the permissions you need (repo, issue, etc.)
 48  
 49  ### 3. Configure Your AI Assistant
 50  
 51  Add this to your MCP configuration file:
 52  
 53  **For stdio mode** (most common):
 54  
 55  ```json
 56  {
 57    "mcpServers": {
 58      "forgejo": {
 59        "command": "forgejo-mcp",
 60        "args": [
 61          "--transport", "stdio",
 62          "--url", "https://your-forgejo-instance.org"
 63        ],
 64        "env": {
 65          "FORGEJO_ACCESS_TOKEN": "<your personal access token>",
 66          "FORGEJO_USER_AGENT": "forgejo-mcp/1.0.0"
 67        }
 68      }
 69    }
 70  }
 71  ```
 72  
 73  **For streamable HTTP mode** (recommended for remote/Claude.ai):
 74  
 75  ```json
 76  {
 77    "mcpServers": {
 78      "forgejo": {
 79        "url": "http://localhost:8080/mcp"
 80      }
 81    }
 82  }
 83  ```
 84  
 85  When using streamable HTTP mode, start the server first:
 86  
 87  ```bash
 88  forgejo-mcp --transport http --url https://your-forgejo-instance.org --token <your-token>
 89  ```
 90  
 91  **For SSE mode** (legacy HTTP-based):
 92  
 93  ```json
 94  {
 95    "mcpServers": {
 96      "forgejo": {
 97        "url": "http://localhost:8080/sse"
 98      }
 99    }
100  }
101  ```
102  
103  When using SSE mode, start the server first:
104  
105  ```bash
106  forgejo-mcp --transport sse --url https://your-forgejo-instance.org --token <your-token>
107  ```
108  
109  ### 4. Start Using It
110  
111  Open your MCP-compatible AI assistant and try:
112  
113  ```
114  List all my repositories
115  ```
116  
117  ## Available Tools
118  
119  | Tool | Description |
120  |------|-------------|
121  | **User** | |
122  | `get_my_user_info` | Get information about the authenticated user |
123  | `check_notifications` | Check and list user notifications |
124  | `get_notification_thread` | Get detailed info on a single notification thread |
125  | `mark_notification_read` | Mark a single notification thread as read |
126  | `mark_all_notifications_read` | Acknowledge all notifications |
127  | `list_repo_notifications` | Filter notifications scoped to a single repository |
128  | `mark_repo_notifications_read` | Mark all notifications in a specific repo as read |
129  | `search_users` | Search for users |
130  | **Repositories** | |
131  | `list_my_repos` | List all repositories you own |
132  | `create_repo` | Create a new repository |
133  | `fork_repo` | Fork a repository |
134  | `search_repos` | Search for repositories |
135  | **Branches** | |
136  | `list_branches` | List all branches in a repository |
137  | `create_branch` | Create a new branch |
138  | `delete_branch` | Delete a branch |
139  | **Files** | |
140  | `get_file_content` | Get the content of a file |
141  | `create_file` | Create a new file |
142  | `update_file` | Update an existing file |
143  | `delete_file` | Delete a file |
144  | **Commits** | |
145  | `list_repo_commits` | List commits in a repository |
146  | **Issues** | |
147  | `list_repo_issues` | List issues in a repository |
148  | `get_issue_by_index` | Get a specific issue |
149  | `create_issue` | Create a new issue |
150  | `add_issue_labels` | Add labels to an issue (requires numeric label IDs) |
151  | `remove_issue_labels` | Remove labels from an issue (requires numeric label IDs) |
152  | `update_issue` | Update an existing issue (requires numeric milestone ID) |
153  | `issue_state_change` | Open or close an issue |
154  | `list_repo_milestones` | List milestones with their IDs (use with `update_issue`) |
155  | `list_repo_labels` | List labels with their IDs (use with `add_issue_labels`, `remove_issue_labels`) |
156  | **Comments** | |
157  | `list_issue_comments` | List comments on an issue or PR |
158  | `get_issue_comment` | Get a specific comment |
159  | `create_issue_comment` | Add a comment to an issue or PR |
160  | `edit_issue_comment` | Edit a comment |
161  | `delete_issue_comment` | Delete a comment |
162  | **Pull Requests** | |
163  | `list_repo_pull_requests` | List pull requests in a repository |
164  | `get_pull_request_by_index` | Get a specific pull request |
165  | `create_pull_request` | Create a new pull request |
166  | `update_pull_request` | Update an existing pull request |
167  | `list_pull_reviews` | List reviews for a pull request |
168  | `get_pull_review` | Get a specific pull request review |
169  | `list_pull_review_comments` | List comments on a pull request review |
170  | **Actions** | |
171  | `dispatch_workflow` | Trigger a workflow run via `workflow_dispatch` event |
172  | `list_workflow_runs` | List workflow runs with optional filtering by status, event, or SHA |
173  | `get_workflow_run` | Get details of a specific workflow run by ID |
174  | **Organizations** | |
175  | `search_org_teams` | Search for teams in an organization |
176  | **Server** | |
177  | `get_forgejo_mcp_server_version` | Get the MCP server version |
178  
179  ## CLI Mode
180  
181  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.
182  
183  ```bash
184  # List all available tools (grouped by domain)
185  forgejo-mcp --cli list
186  
187  # Invoke a tool with JSON arguments
188  forgejo-mcp --cli get_issue_by_index --args '{"owner":"goern","repo":"forgejo-mcp","index":1}'
189  
190  # Pipe JSON arguments via stdin
191  echo '{"owner":"goern","repo":"forgejo-mcp"}' | forgejo-mcp --cli list_repo_issues
192  
193  # List recent workflow runs (text output)
194  forgejo-mcp --cli list_workflow_runs \
195    --args '{"owner":"goern","repo":"forgejo-mcp"}' \
196    --output=text
197  
198  # List only failed runs
199  forgejo-mcp --cli list_workflow_runs \
200    --args '{"owner":"goern","repo":"forgejo-mcp","status":"failure"}' \
201    --output=text
202  
203  # Show a tool's parameters
204  forgejo-mcp --cli create_issue --help
205  
206  # Control output format (json or text)
207  forgejo-mcp --cli list --output=json
208  forgejo-mcp --cli get_my_user_info --args '{}' --output=text
209  ```
210  
211  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.
212  
213  ## Configuration Options
214  
215  You can configure the server using command-line arguments or environment variables:
216  
217  | CLI Argument | Environment Variable | Description |
218  |--------------|---------------------|-------------|
219  | `--url` | `FORGEJO_URL` | Your Forgejo instance URL |
220  | `--token` | `FORGEJO_ACCESS_TOKEN` | Your personal access token |
221  | `--debug` | `FORGEJO_DEBUG` | Enable debug mode |
222  | `--transport` | - | Transport mode: `stdio`, `sse`, or `http` |
223  | `--sse-port` | - | Port for SSE mode (default: 8080) |
224  | `--http-port` | - | Port for streamable HTTP mode (default: 8080) |
225  | `--cli` | - | Enter CLI mode for direct tool invocation |
226  | `--user-agent` | `FORGEJO_USER_AGENT` | HTTP User-Agent header (default: `forgejo-mcp/<version>`) |
227  
228  Command-line arguments take priority over environment variables.
229  
230  ## Troubleshooting
231  
232  **Enable debug mode** to see detailed logs:
233  
234  ```bash
235  forgejo-mcp --transport sse --url <url> --token <token> --debug
236  ```
237  
238  Or set the environment variable:
239  
240  ```bash
241  export FORGEJO_DEBUG=true
242  ```
243  
244  **Custom User-Agent**: If your Forgejo instance or proxy blocks the default `go-http-client` user agent, set a custom one:
245  
246  ```bash
247  # Via environment variable
248  export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"
249  
250  # Or via CLI flag
251  forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url <url> --token <token>
252  ```
253  
254  ## Getting Help
255  
256  - [Report issues](https://codeberg.org/goern/forgejo-mcp/issues)
257  - [View source code](https://codeberg.org/goern/forgejo-mcp)
258  
259  ## For Developers
260  
261  See [DEVELOPER.md](DEVELOPER.md) for build instructions, architecture overview, and contribution guidelines.
262  
263  ## Known Issues
264  
265  - **`go install ...@latest` fails** — The `go.mod` contains a `replace` directive (for a forked Forgejo SDK), which prevents remote `go install`. Use the clone-and-build workflow shown in [Quick Start](#quick-start) instead. Tracked in [#67](https://codeberg.org/goern/forgejo-mcp/issues/67).
266  
267  ## Contributors
268  
269  forgejo-mcp is shaped by everyone who files issues, writes code, reviews PRs, and pushes the project forward. Thank you all. 🙏
270  
271  ### Code contributors
272  
273  | Contributor | Highlights |
274  |-------------|------------|
275  | [goern](https://codeberg.org/goern) (Christoph Görn) | Project creator and maintainer |
276  | Ronmi Ren | Co-creator; SSE/HTTP transport, issue blocking, CI/CD improvements, logo, Glama spec |
277  | [twstagg](https://codeberg.org/twstagg) (Tristin Stagg) | User agent configuration support (PR #89) |
278  | [mattdm](https://codeberg.org/mattdm) (Matthew Miller) | Logging improvements, FORGEJO_* migration, README, URL refactor |
279  | [byteflavour](https://codeberg.org/byteflavour) | `check_notifications` + full notification management API (PR #84, #86); feature requests #80, #85 |
280  | [jesterret](https://codeberg.org/jesterret) | Pull request reviews and comments support (PR #51) |
281  | [appleboy](https://codeberg.org/appleboy) | Custom SSE port support, bug fixes |
282  | [ignasgil](https://codeberg.org/ignasgil) | `remove_issue_labels` tool (PR #96) |
283  | [dmikushin](https://codeberg.org/dmikushin) (Dmitry Mikushin) | Fix string-encoded number parameter parsing from MCP clients (PR #93) |
284  | [jiriks74](https://codeberg.org/jiriks74) | mcp-go v0.44.0 dependency update (PR #90) |
285  | [th](https://codeberg.org/th) (Tomi Haapaniemi) | `update_pull_request` tool |
286  | [hiifong](https://codeberg.org/hiifong) | Early bug fixes and updates |
287  | [Lunny Xiao](https://codeberg.org/lunny) | Early contributions |
288  | [techknowlogick](https://codeberg.org/techknowlogick) | Early contributions |
289  | [yp05327](https://codeberg.org/yp05327) | Early contributions |
290  | [mw75](https://codeberg.org/mw75) | Owner/org support for repo creation (PR #18) |
291  | [Dax Kelson](https://codeberg.org/dkelson) | Issue comment management (PR #34) |
292  | [Guruprasad Kulkarni](https://codeberg.org/comdotlinux) | Arch Linux AUR installation docs (PR #69) |
293  | [Mario Wolff](https://codeberg.org/mariowolff) | Contributions |
294  | [Massimo Fraschetti](https://codeberg.org/fraschetti) | Contributions |
295  
296  ### Community contributors
297  
298  Issue reporters and discussion participants who shaped the direction of the project:
299  
300  | Contributor | Contributions |
301  |-------------|--------------|
302  | [byteflavour](https://codeberg.org/byteflavour) | Filed #80 (milestone/label discovery), #85 (notification API proposal); active reviewer in discussions |
303  | [choucavalier](https://codeberg.org/choucavalier) | Filed #82 (fix skill), #70 (macOS arm64 releases), #62 (binary releases & mise support) |
304  | [MalcolmMielle](https://codeberg.org/MalcolmMielle) | Filed #59 (PR review tools — since implemented) |
305  | [redbeard](https://codeberg.org/redbeard) | Filed #60 (Actions support — since implemented) |
306  | [c6sepl6p](https://codeberg.org/c6sepl6p) | Filed #72 (base64 encoding), #54 (merge pull request — since implemented) |
307  | [malik](https://codeberg.org/malik) | Filed #73 (version flag), #47 (Nix build fix) |
308  | [a2800276](https://codeberg.org/a2800276) | Filed #74 (OpenAI compatibility) |
309  | [simenandre](https://codeberg.org/simenandre) | Filed #49 (go install support) |
310  | [BasdP](https://codeberg.org/BasdP) | Filed #42 (Projects support) |
311  | [BoBeR182](https://codeberg.org/BoBeR182) | Filed #32 (wiki support) |
312  | [ignasgil](https://codeberg.org/ignasgil) | Filed #95 (`remove_issue_labels` feature request) |
313  | [Vokuar](https://codeberg.org/Vokuar) | Filed #99 (streamable HTTP transport support) |
314  | [janbaer](https://codeberg.org/janbaer) | Filed #98 (reply to review comment) |
315  | [fraschm98](https://codeberg.org/fraschm98) | Early issue reports |
316  
317  ### Cyborg contributors
318  
319  This project also received contributions from AI coding agents — submitted as regular PRs, reviewed by humans:
320  
321  | Agent | Role | Contributions |
322  |-------|------|---------------|
323  | [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 |
324  | opencode | AI dev agent | Pull request reviews and comments support (PR #51) |
325  | b4mad-release-bot | Release automation | Automated changelog and release tagging |
326  | the #B4mad Renovate bot | Dependency updates | Automated dependency upgrades |
327  
328  Want to contribute? Open an issue or pull request — all are welcome.
329  
330  
331  ## License
332  
333  This project is open source. See the repository for license details.