Forgejo MCP Server

Connect your AI assistant to Forgejo repositories. Manage issues, pull requests, files, and more through natural language.

What It Does

Forgejo MCP Server is an integration plugin that connects Forgejo with Model Context Protocol (MCP) systems. Once configured, you can interact with your Forgejo repositories through any MCP-compatible AI assistant like Claude, Cursor, or VS Code extensions.

Example commands you can use:

• "List all my repositories"
• "Create an issue titled 'Bug in login page'"
• "Show me open pull requests in my-org/my-repo"
• "Get the contents of README.md from the main branch"

Quick Start

1. Install

Option A: Using Go (Recommended)

go install codeberg.org/goern/forgejo-mcp/v2@latest

Ensure $GOPATH/bin (typically ~/go/bin) is in your PATH.

Option B: Download Binary

Download the latest release from the releases page.

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": ""
      }
    }
  }
}

For SSE mode (HTTP-based):

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/sse"
    }
  }
}

When using SSE mode, start the server first:

forgejo-mcp --transport sse --url https://your-forgejo-instance.org --token

4. Start Using It

Open your MCP-compatible AI assistant and try:

List all my repositories

Available Tools

Configuration Options

You can configure the server using command-line arguments or environment variables:

Command-line arguments take priority over environment variables.

Troubleshooting

Enable debug mode to see detailed logs:

forgejo-mcp --transport sse --url  --token  --debug

Or set the environment variable:

export FORGEJO_DEBUG=true

Getting Help

• Report issues
• View source code

For Developers

See DEVELOPER.md for build instructions, architecture overview, and contribution guidelines.

License

This project is open source. See the repository for license details.