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.

For Arch Linux, use your favorite AUR helper:

yay -S forgejo-mcp # builds from source
yay -S forgejo-mcp-bin # uses pre-built binary

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": "<your personal 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 <your-token>

4. Start Using It

Open your MCP-compatible AI assistant and try:

List all my repositories

Available Tools

CLI Mode

You can invoke any tool directly from the command line without running an MCP server. This is useful for shell scripts, CI/CD pipelines, and Claude Code skills.

# List all available tools (grouped by domain)
forgejo-mcp --cli list
# Invoke a tool with JSON arguments
forgejo-mcp --cli get_issue_by_index --args '{"owner":"goern","repo":"forgejo-mcp","index":1}'
# Pipe JSON arguments via stdin
echo '{"owner":"goern","repo":"forgejo-mcp"}' | forgejo-mcp --cli list_repo_issues
# Show a tool's parameters
forgejo-mcp --cli create_issue --help
# Control output format (json or text)
forgejo-mcp --cli list --output=json
forgejo-mcp --cli get_my_user_info --args '{}' --output=text

CLI mode requires the same FORGEJO_URL and FORGEJO_ACCESS_TOKEN configuration as MCP server mode. Tool results are written as JSON to stdout by default; errors go to stderr with a non-zero exit code.

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 <url> --token <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.