Gitea/Forgejo MCP Server

1# Gitea/Forgejo MCP Server
2 
3> Turn AI into your code repository management assistant
4 
5A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables you to manage Gitea/Forgejo repositories through AI assistants like Claude, Gemini, and Copilot.
6 
7## 🚀 Why Use Forgejo MCP Server?
8 
9If you want to:
10- **Smart progress tracking**: Let AI help you track project progress and analyze bottlenecks
11- **Automated issue categorization**: Automatically tag issue labels and set milestones based on content
12- **Priority sorting**: Let AI analyze issue content to help prioritize tasks
13- **Code review assistance**: Get AI suggestions and insights in Pull Requests
14- **Project documentation organization**: Automatically organize Wiki documents and release notes
15 
16Then this tool is made for you!
17 
18## ✨ Supported Features
19 
20### Issue Management
21- Create, edit, and view issues
22- Add, remove, and replace labels
23- Manage issue comments and attachments
24- Set issue dependencies
25 
26### Project Organization
27- Manage labels (create, edit, delete)
28- Manage milestones (create, edit, delete)
29- Repository search and listing
30 
31### Release Management
32- Manage version releases
33- Manage release attachments
34 
35### Other Features
36- View Pull Requests
37- Manage Wiki pages
38- View Forgejo/Gitea Actions tasks
39 
40## 📦 Installation
41 
42### Method 1: Use docker (Recommended)
43 
44For STDIO mode, you can skip to **Usage** section.
45 
46For SSE/Streamable HTTP mode, you should run `forgejo-mcp` as server before configuring your MCP client.
47 
48```bash
49docker run -p 8080:8080 -e FORGEJOMCP_TOKEN="my-forgejo-api-token" ronmi/forgejo-mcp http --address :8080 --server https://git.example.com
50```
51 
52### Method 2: Install from source
53 
54```bash
55go install github.com/raohwork/forgejo-mcp@latest
56```
57 
58### Method 3: Download Pre-compiled Binaries
59 
60Download the appropriate version for your operating system from the [Releases page](https://github.com/raohwork/forgejo-mcp/releases).
61 
62## 🖥️ Usage
63 
64This tool provides two primary modes of operation: `stdio` for local integration and `http` for remote access.
65 
66Before actually setup you MCP client, you have to create an access token on the Forgejo/Gitea server.
67 
681. Log in to your Forgejo/Gitea instance
692. Go to **Settings** → **Applications** → **Access Tokens**
703. Click **Generate New Token**
714. Select appropriate permission scopes (recommend at least `repository` and `issue` write permissions)
725. Copy the generated token
73 
74💡 **Tip**: For security, consider setting environment variables instead of using tokens directly in config:
75```bash
76export FORGEJOMCP_SERVER="https://your-forgejo-instance.com"
77export FORGEJOMCP_TOKEN="your_access_token"
78```
79 
80### Stdio Mode (for Local Clients)
81 
82This is the recommended mode for integrating with local AI assistant clients like Claude Desktop or Gemini CLI. It uses standard input/output for direct communication.
83 
84#### Configure Your AI Client
85 
86Using docker:
87 
88```json
89{
90  "mcpServers": {
91    "forgejo": {
92      "command": "docker",
93      "args": [
94        "--rm",
95        "ronmi/forgejo-mcp",
96        "stdio",
97        "--server", "https://your-forgejo-instance.com",
98        "--token", "your_access_token"
99      ]
100    }
101  }
102}
103```
104 
105Installed from source or pre-built binary:
106 
107```json
108{
109  "mcpServers": {
110    "forgejo": {
111      "command": "/path/to/forgejo-mcp",
112      "args": [
113        "stdio",
114        "--server", "https://your-forgejo-instance.com",
115        "--token", "your_access_token"
116      ]
117    }
118  }
119}
120```
121 
122You might want to take a look at **Security Recommendations** section for best practice.
123 
124### HTTP Server Mode (for Remote Access)
125 
126This mode starts a web server, allowing remote clients to connect via HTTP. It's ideal for web-based services or setting up a central gateway for multiple users.
127 
128Run the following command to start the server:
129```bash
130# with local binary
131/path/to/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com
132 
133# with docker
134docker run -p 8080:8080 -d --rm ronmi/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com
135```
136 
137The server supports two operational modes:
138- **Single-user mode**: If you provide a `--token` (or environment variable `FORGEJOMCP_TOKEN`) at startup, all operations will use that token.
139  ```bash
140  forgejo-mcp http --address :8080 --server https://git.example.com --token your_token
141  ```
142- **Multi-user mode**: If no token is provided, the server requires clients to send an `Authorization: Bearer <token>` header with each request, allowing it to serve multiple users securely.
143 
144#### Client Configuration
145 
146For clients that support connecting to a remote MCP server via HTTP, you can add a configuration like this. This example shows how to connect to a server running in multi-user mode:
147 
148```json
149{
150  "mcpServers": {
151    "forgejo-remote": {
152      "type": "sse",
153      "url": "http://localhost:8080/sse",
154      "headers": {
155        "Authorization": "Bearer your_token"
156      }
157    }
158  }
159}
160```
161 
162or `http` type (for Streamable HTTP, use different path in URL)
163 
164```json
165{
166  "mcpServers": {
167    "forgejo-remote": {
168      "type": "http",
169      "url": "http://localhost:8080/",
170      "headers": {
171        "Authorization": "Bearer your_token"
172      }
173    }
174  }
175}
176```
177 
178If connecting to a server in single-user mode, you can omit the `headers` field.
179 
180## 🛡️ Security Recommendations
181 
1821. **Use environment variables**: Set `FORGEJOMCP_SERVER` and `FORGEJOMCP_TOKEN`, then remove `--server` and `--token` from your configuration
1832. **Limit token permissions**: Only grant necessary permission scopes
1843. **Rotate tokens regularly**: Update access tokens periodically
185 
186## 📋 Usage Examples
187 
188After configuration, you can use natural language in your AI assistant to manage your repositories:
189 
190```
191"Show me critical bug reports of this repo on my gitea server"
192 
193"According to our discussion above, create a detailed issue about this bug, then leave a comment on the issue to describe how we will fix it."
194 
195"Give me a report about current milestone. Recent progression in particular."
196 
197"Analyze recent pull requests and tell me which ones need priority review"
198```
199 
200## 🤝 Support & Contributing
201 
202- **Bug Reports**: [GitHub Issues](https://github.com/raohwork/forgejo-mcp/issues)
203- **Code Contributions**: Pull Requests are welcome!
204 
205## 📄 License
206 
207This project is licensed under the [Mozilla Public License 2.0](LICENSE).
208 
209---
210 
211**Start making AI your code repository management partner!** 🚀
212