Forgejo Repository Interaction Service (MCP)

This component, the Forgejo MCP Connector, functions as an intermediary service, bridging the capabilities of a Forgejo instance with systems adhering to the Model Context Protocol (MCP). This integration permits users to manage source code repositories and trigger auxiliary operations through a conversational, MCP-compliant interface.

🚧Deployment Guidelines

🔧Source Compilation

The operational binary can be obtained by cloning the official source repository:

git clone https://codeberg.org/goern/forgejo-mcp.git

Prerequisites for successful compilation include:

• The make utility.
• A contemporary installation of the Golang compiler (version 1.24 or newer is suggested).

Execute the build process with:

make build

📁System Path Integration

After compilation, relocate the generated executable, named forgejo-mcp, into a directory registered within your system's execution search path (PATH). A common location is:

cp forgejo-mcp /usr/local/bin/

🚀Operational Configuration

This setup example targets utilization within environments like Cursor or VSCode plugins utilizing MCP. To register the Forgejo service endpoint within your primary MCP configuration artifact, incorporate the following structure:

• Standard I/O Transport Mode

{
  "mcpServers": {
    "forgejo": {
      "command": "forgejo-mcp",
      "args": [
        "--transport", "stdio",
        "--url", "https://forgejo.example.org"
        // Omit or uncomment: "--token", "<your secret access credential>"
      ],
      "env": {
        // Environment variable overrides are possible:
        // "FORGEJO_URL": "https://forgejo.example.org",
        "FORGEJO_ACCESS_TOKEN": "<your personal access token>"
      }
    }
  }
}

• Server-Sent Events (SSE) Transport Mode

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

[!CAUTION] The Forgejo base address and secret authentication key can be supplied via command-line parameters or environment variables. Command-line arguments always take precedence. Environment variable mapping has been standardized: - Utilize FORGEJO_URL in place of the legacy GITEA_HOST identifier. - Use FORGEJO_ACCESS_TOKEN instead of the retired GITEA_ACCESS_TOKEN setting. - Employ FORGEJO_DEBUG for toggling verbosity, replacing GITEA_DEBUG.

Previous GITEA_* environmental variables remain functional for compatibility but will trigger advisory warnings.

Upon successful provisioning, initiate interaction via the MCP client by issuing commands such as:

list all my repositories

✅Exposed Functionality

The Forgejo MCP Server exposes the following capabilities for external invocation:

Function Name	Target Scope	Detailed Capability
get_my_user_info	User	Retrieves details for the currently authenticated identity
create_repo	Repository	Provisions a new repository instance
fork_repo	Repository	Generates a copy (fork) of an existing repository
list_my_repos	Repository	Enumerates all repositories held by the user
create_branch	Branch	Establishes a new branch reference within a project
delete_branch	Branch	Removes a specified branch from tracking
list_branches	Branch	Displays all active branches associated with a repository
list_repo_commits	Commit	Fetches the chronological history of commits for a repository
get_file_content	File	Fetches the payload and metadata for a specific file
create_file	File	Injects a novel file object into the repository tree
update_file	File	Modifies the contents of an existing file
delete_file	File	Permanently removes a designated file from the repository
get_issue_by_index	Issue	Fetches a specific issue based on its unique sequential identifier
list_repo_issues	Issue	Presents the catalog of issues pertaining to a repository
create_issue	Issue	Logs a new problem or feature request entry
create_issue_comment	Issue	Attaches a commentary note to an existing issue
get_pull_request_by_index	Pull Request	Retrieves a specific merge request by its index number
list_repo_pull_requests	Pull Request	Lists all outstanding merge requests for the repository
create_pull_request	Pull Request	Submits a proposal to merge changes between branches
search_users	User	Performs a lookup operation across registered users
search_org_teams	Organization	Searches for defined groups within an organizational structure
search_repos	Repository	Executes a query to locate relevant repositories
get_forgejo_mcp_server_version	Server	Reports the current installed version number of this connector service

🐛Diagnostics Mode

To activate verbose logging, append the -d parameter when invoking the service using the SSE communication protocol:

./forgejo-mcp --transport sse --url <forgejo-url> [--sse-port 8080] --token <your personal access token> --debug

We encourage exploration and streamlined repository oversight through this chat-enabled interface!