# Forgejo Mcp

> A MCP server that enables you to manage Gitea/Forgejo repositories through AI assistants

- **Type:** MCP server
- **Install:** `agentstack add mcp-raohwork-forgejo-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raohwork](https://agentstack.voostack.com/s/raohwork)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MPL-2.0
- **Upstream author:** [raohwork](https://github.com/raohwork)
- **Source:** https://github.com/raohwork/forgejo-mcp

## Install

```sh
agentstack add mcp-raohwork-forgejo-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Gitea/Forgejo MCP Server

> Turn AI into your code repository management assistant

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables you to manage Gitea/Forgejo repositories through AI assistants like Claude, Gemini, and Copilot.

## 🚀 Why Use Forgejo MCP Server?

If you want to:
- **Smart progress tracking**: Let AI help you track project progress and analyze bottlenecks
- **Automated issue categorization**: Automatically tag issue labels and set milestones based on content
- **Priority sorting**: Let AI analyze issue content to help prioritize tasks
- **Code review assistance**: Get AI suggestions and insights in Pull Requests
- **Project documentation organization**: Automatically organize Wiki documents and release notes

Then this tool is made for you!

## ✨ Supported Features

### Issue Management
- Create, edit, and view issues
- Add, remove, and replace labels
- Manage issue comments and attachments
- Set issue dependencies

### Project Organization
- Manage labels (create, edit, delete)
- Manage milestones (create, edit, delete)
- Repository search and listing

### Release Management
- Manage version releases
- Manage release attachments

### Other Features
- View Pull Requests
- Manage Wiki pages
- View Forgejo/Gitea Actions tasks

## 📦 Installation

### Method 1: Use docker (Recommended)

For STDIO mode, you can skip to **Usage** section.

For SSE/Streamable HTTP mode, you should run `forgejo-mcp` as server before configuring your MCP client.

```bash
docker run -p 8080:8080 -e FORGEJOMCP_TOKEN="my-forgejo-api-token" ronmi/forgejo-mcp http --address :8080 --server https://git.example.com
```

### Method 2: Install from source

```bash
go install github.com/raohwork/forgejo-mcp@latest
```

### Method 3: Download Pre-compiled Binaries

Download the appropriate version for your operating system from the [Releases page](https://github.com/raohwork/forgejo-mcp/releases).

## 🖥️ Usage

This tool provides two primary modes of operation: `stdio` for local integration and `http` for remote access.

Before actually setup you MCP client, you have to create an access token on the Forgejo/Gitea server.

1. Log in to your Forgejo/Gitea instance
2. Go to **Settings** → **Applications** → **Access Tokens**
3. Click **Generate New Token**
4. Select appropriate permission scopes (recommend at least `repository` and `issue` write permissions)
5. Copy the generated token

💡 **Tip**: For security, consider setting environment variables instead of using tokens directly in config:
```bash
export FORGEJOMCP_SERVER="https://your-forgejo-instance.com"
export FORGEJOMCP_TOKEN="your_access_token"
```

### Stdio Mode (for Local Clients)

This 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.

#### Configure Your AI Client

Using docker:

```json
{
  "mcpServers": {
    "forgejo": {
      "command": "docker",
      "args": [
        "--rm",
        "ronmi/forgejo-mcp",
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}
```

Installed from source or pre-built binary:

```json
{
  "mcpServers": {
    "forgejo": {
      "command": "/path/to/forgejo-mcp",
      "args": [
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}
```

You might want to take a look at **Security Recommendations** section for best practice.

### HTTP Server Mode (for Remote Access)

This 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.

Run the following command to start the server:
```bash
# with local binary
/path/to/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

# with docker
docker run -p 8080:8080 -d --rm ronmi/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com
```

The server supports two operational modes:
- **Single-user mode**: If you provide a `--token` (or environment variable `FORGEJOMCP_TOKEN`) at startup, all operations will use that token.
  ```bash
  forgejo-mcp http --address :8080 --server https://git.example.com --token your_token
  ```
- **Multi-user mode**: If no token is provided, the server requires clients to send an `Authorization: Bearer ` header with each request, allowing it to serve multiple users securely.

#### Client Configuration

For 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:

```json
{
  "mcpServers": {
    "forgejo-remote": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}
```

or `http` type (for Streamable HTTP, use different path in URL)

```json
{
  "mcpServers": {
    "forgejo-remote": {
      "type": "http",
      "url": "http://localhost:8080/",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}
```

If connecting to a server in single-user mode, you can omit the `headers` field.

## 🛡️ Security Recommendations

1. **Use environment variables**: Set `FORGEJOMCP_SERVER` and `FORGEJOMCP_TOKEN`, then remove `--server` and `--token` from your configuration
2. **Limit token permissions**: Only grant necessary permission scopes
3. **Rotate tokens regularly**: Update access tokens periodically

## 📋 Usage Examples

After configuration, you can use natural language in your AI assistant to manage your repositories:

```
"Show me critical bug reports of this repo on my gitea server"

"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."

"Give me a report about current milestone. Recent progression in particular."

"Analyze recent pull requests and tell me which ones need priority review"
```

## 🤝 Support & Contributing

- **Bug Reports**: [GitHub Issues](https://github.com/raohwork/forgejo-mcp/issues)
- **Code Contributions**: Pull Requests are welcome!

## 📄 License

This project is licensed under the [Mozilla Public License 2.0](LICENSE).

---

**Start making AI your code repository management partner!** 🚀

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [raohwork](https://github.com/raohwork)
- **Source:** [raohwork/forgejo-mcp](https://github.com/raohwork/forgejo-mcp)
- **License:** MPL-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-raohwork-forgejo-mcp
- Seller: https://agentstack.voostack.com/s/raohwork
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.