Forgejo MCP Server Integration

Overview

This project extends the Model Context Protocol (MCP) architecture by integrating it directly with Forgejo, the open-source and self-hosted Git service (a community-driven fork of Gitea).

While the MCP ecosystem is rapidly expanding across AI and automation platforms, Forgejo had no official MCP support - neither from the Forgejo team nor the broader open-source community. To fill this gap, I built a Forgejo MCP Server that allows AI agents and automation systems to communicate directly with Forgejo repositories and services through standardized protocol messages.

The result is a context-aware integration layer where AI agents can perform repository operations, manage files, interact with wikis, and publish releases - all through a single MCP-compatible interface.

Core Components

1. Protocol Layer

Implements the official @modelcontextprotocol/sdk, providing a fully compliant MCP interface. Supports both stdio and streamable-http modes for flexible client communication.

2. Forgejo Adapter Layer

The Forgejo adapter translates MCP actions into Forgejo API calls while preserving context. It acts as a two-way bridge between AI agents and Forgejo's REST endpoints.

These actions expose Forgejo's capabilities in a structured, language-model-friendly way - enabling AI agents (like LangChain or custom assistants) to perform repository management tasks using natural language.

Self-hosted DevOps infrastructure with AI capabilities

Security Model

The Forgejo MCP Server supports two authentication patterns, depending on your deployment context:

This flexibility allows teams to start simple and scale their authentication as needs evolve, without changing the MCP protocol integration.

System Architecture

The system follows a three-layer approach with clear separation of concerns:

┌──────────────────────────────────────────────────────────────┐
│                       MCP Protocol Layer                     │
│   (FastAPI + MCP SDK, stdio/streamable-http modes)          │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                    Forgejo Adapter Layer                     │
│  Actions: repo.list, file.write, wiki.update, release.*     │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                    Forgejo REST API                          │
│         (Self-hosted Git server with package registry)       │
└──────────────────────────────────────────────────────────────┘

Each layer is independently testable and can be scaled or replaced as requirements evolve.

Example Workflow

Here's how an AI agent might use the MCP server to create a new release after a successful CI pipeline:

This workflow demonstrates the power of protocol-driven automation - the AI agent never touches the Forgejo API directly, yet performs complex repository operations.

Key Insights

• Protocol Over REST: By abstracting Forgejo's API behind MCP, we unlock compatibility with any MCP-compliant client (Claude Desktop, custom agents, LangChain tools) without client-side Forgejo knowledge.
• Security Simplicity: Supporting both single-user and multi-user modes keeps the system flexible. Most self-hosted users start with single-user mode, then migrate to multi-user when scaling teams.
• Open Source Value: Forgejo being a community fork of Gitea means this project serves users who prioritize self-hosting, privacy, and avoiding vendor lock-in.

Technical Stack

The project leverages modern Python technologies and best practices: