Forgejo MCP Server

An MCP (Model Context Protocol) server that provides full API coverage for Forgejo deployments, enabling AI assistants to interact with repositories, issues, pull requests, users, organizations, and more.

Features

• Repository Management: List, create, delete, and fork repositories
• Issue Tracking: Create, update, and comment on issues
• Pull Requests: Create, review, and merge pull requests
• Branch Operations: List, create, and delete branches
• File Operations: Read, create, update, and delete files
• User Management: Get user information and list repositories
• Organization Support: List and manage organization resources
• Release Management: Create and manage releases
• Search: Search repositories, issues, users, and code

Quick Start

The easiest way to use this MCP server is with the pre-built container image.

Container Image

podman pull registry.timfinn.dev/timothy/forgejo-mcp:latest

Available tags:

• latest - Latest build from main branch
• v0.1.0 - Stable release versions

Claude Code Configuration

Add to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "forgejo": {
      "command": "podman",
      "args": ["run", "-i", "--rm", "-e", "FORGEJO_URL", "-e", "FORGEJO_TOKEN",
               "registry.timfinn.dev/timothy/forgejo-mcp:latest"],
      "env": {
        "FORGEJO_URL": "https://your-forgejo-instance.com",
        "FORGEJO_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Claude Code after adding the configuration.

Deployment as a Service (Docker/Unraid)

The MCP server supports HTTP transport, allowing it to run as a persistent network service.

Docker Compose

services:
  forgejo-mcp:
    image: registry.timfinn.dev/timothy/forgejo-mcp:latest
    environment:
      - TRANSPORT=http
      - PORT=3000
      - FORGEJO_URL=https://your-forgejo-instance.com
      - FORGEJO_TOKEN=your-api-token
    ports:
      - "3000:3000"
    restart: unless-stopped

Unraid

1. Add a new container in Unraid's Docker tab
2. Set the repository to: registry.timfinn.dev/timothy/forgejo-mcp:latest
3. Add environment variables:
   • TRANSPORT=http
   • PORT=3000
   • FORGEJO_URL=https://your-forgejo-instance.com
   • FORGEJO_TOKEN=your-api-token
4. Add port mapping: 3000:3000

Endpoints

When running in HTTP mode, the server exposes:

• POST /mcp - Streamable HTTP endpoint for MCP connections
• GET /health - Health check endpoint

Claude Code Configuration (HTTP mode)

{
  "mcpServers": {
    "forgejo": {
      "url": "http://your-server:3000/mcp"
    }
  }
}

Configuration

Required Environment Variables

• FORGEJO_URL - Base URL of your Forgejo instance (e.g., https://codeberg.org)
• FORGEJO_TOKEN - API token for authentication (generate in Forgejo: Settings > Applications > Generate New Token)

Optional Environment Variables

• TRANSPORT - Transport mode: stdio (default) or http
• PORT - Port for HTTP mode (default: 3000)

Building from Source

Prerequisites

• Go 1.23+

Build

git clone https://git.timfinn.dev/timothy/forgejo-mcp.git
cd forgejo-mcp
go build -o forgejo-mcp .

Run Locally

FORGEJO_URL=https://your-forgejo.com FORGEJO_TOKEN=your-token ./forgejo-mcp

Build Container

podman build -f Containerfile -t forgejo-mcp .

Available Tools (45 total)

Repository Tools

Tool	Description
list_repositories	List repositories for the authenticated user
get_repository	Get details of a specific repository
create_repository	Create a new repository
create_org_repository	Create a repository in an organization
delete_repository	Delete a repository
fork_repository	Fork a repository
list_forks	List forks of a repository

Issue Tools

Tool	Description
list_issues	List issues in a repository
get_issue	Get details of a specific issue
create_issue	Create a new issue
update_issue	Update an existing issue
list_issue_comments	List comments on an issue
create_issue_comment	Add a comment to an issue

Pull Request Tools

Tool	Description
list_pull_requests	List pull requests in a repository
get_pull_request	Get details of a pull request
create_pull_request	Create a new pull request
update_pull_request	Update a pull request
merge_pull_request	Merge a pull request
list_pr_commits	List commits in a pull request
list_pr_files	List changed files in a pull request

Branch Tools

Tool	Description
list_branches	List branches in a repository
get_branch	Get details of a branch
create_branch	Create a new branch
delete_branch	Delete a branch

File Tools

Tool	Description
get_file_contents	Get contents of a file
get_directory_contents	List contents of a directory
create_file	Create a new file
update_file	Update an existing file
delete_file	Delete a file

User Tools

Tool	Description
get_authenticated_user	Get current user info
get_user	Get user by username
list_user_repos	List user's repositories
list_user_orgs	List user's organizations

Organization Tools

Tool	Description
list_organizations	List organizations
get_organization	Get organization details
list_org_repos	List organization repositories
list_org_members	List organization members

Release Tools

Tool	Description
list_releases	List releases
get_release	Get release by ID
get_release_by_tag	Get release by tag name
create_release	Create a new release

Search Tools

Tool	Description
search_repositories	Search repositories
search_issues	Search issues and pull requests
search_users	Search users
search_code	Search code (requires indexer)

License

MIT