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"
• "Show me the latest Actions workflow runs in goern/forgejo-mcp"

Quick Start

1. Install

Option A: Using Go (Recommended)

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

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

Note: go install codeberg.org/goern/forgejo-mcp/v2@latest does not work currently. See Known Issues.

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>",
        "FORGEJO_USER_AGENT": "forgejo-mcp/1.0.0"
      }
    }
  }
}

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

Tool	Description
User
get_my_user_info	Get information about the authenticated user
check_notifications	Check and list user notifications
get_notification_thread	Get detailed info on a single notification thread
mark_notification_read	Mark a single notification thread as read
mark_all_notifications_read	Acknowledge all notifications
list_repo_notifications	Filter notifications scoped to a single repository
mark_repo_notifications_read	Mark all notifications in a specific repo as read
search_users	Search for users
Repositories
list_my_repos	List all repositories you own
create_repo	Create a new repository
fork_repo	Fork a repository
search_repos	Search for repositories
Branches
list_branches	List all branches in a repository
create_branch	Create a new branch
delete_branch	Delete a branch
Files
get_file_content	Get the content of a file
create_file	Create a new file
update_file	Update an existing file
delete_file	Delete a file
Commits
list_repo_commits	List commits in a repository
Issues
list_repo_issues	List issues in a repository
get_issue_by_index	Get a specific issue
create_issue	Create a new issue
add_issue_labels	Add labels to an issue (requires numeric label IDs)
update_issue	Update an existing issue (requires numeric milestone ID)
issue_state_change	Open or close an issue
list_repo_milestones	List milestones with their IDs (use with update_issue)
list_repo_labels	List labels with their IDs (use with add_issue_labels)
Comments
list_issue_comments	List comments on an issue or PR
get_issue_comment	Get a specific comment
create_issue_comment	Add a comment to an issue or PR
edit_issue_comment	Edit a comment
delete_issue_comment	Delete a comment
Pull Requests
list_repo_pull_requests	List pull requests in a repository
get_pull_request_by_index	Get a specific pull request
create_pull_request	Create a new pull request
update_pull_request	Update an existing pull request
list_pull_reviews	List reviews for a pull request
get_pull_review	Get a specific pull request review
list_pull_review_comments	List comments on a pull request review
Actions
dispatch_workflow	Trigger a workflow run via workflow_dispatch event
list_workflow_runs	List workflow runs with optional filtering by status, event, or SHA
get_workflow_run	Get details of a specific workflow run by ID
Organizations
search_org_teams	Search for teams in an organization
Server
get_forgejo_mcp_server_version	Get the MCP server version

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

# List recent workflow runs (text output)
forgejo-mcp --cli list_workflow_runs \
  --args '{"owner":"goern","repo":"forgejo-mcp"}' \
  --output=text

# List only failed runs
forgejo-mcp --cli list_workflow_runs \
  --args '{"owner":"goern","repo":"forgejo-mcp","status":"failure"}' \
  --output=text

# 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:

CLI Argument	Environment Variable	Description
--url	FORGEJO_URL	Your Forgejo instance URL
--token	FORGEJO_ACCESS_TOKEN	Your personal access token
--debug	FORGEJO_DEBUG	Enable debug mode
--transport	-	Transport mode: stdio or sse
--sse-port	-	Port for SSE mode (default: 8080)
--cli	-	Enter CLI mode for direct tool invocation
--user-agent	FORGEJO_USER_AGENT	HTTP User-Agent header (default: forgejo-mcp/<version>)

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

Custom User-Agent: If your Forgejo instance or proxy blocks the default go-http-client user agent, set a custom one:

# Via environment variable
export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"

# Or via CLI flag
forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url <url> --token <token>

Getting Help

• Report issues
• View source code

For Developers

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

Known Issues

• go install ...@latest fails — The go.mod contains a replace directive (for a forked Forgejo SDK), which prevents remote go install. Use the clone-and-build workflow shown in Quick Start instead. Tracked in #67.

Contributors

forgejo-mcp is shaped by everyone who files issues, writes code, reviews PRs, and pushes the project forward. Thank you all. 🙏

Code contributors

Contributor	Highlights
goern (Christoph Görn)	Project creator and maintainer
twstagg (Tristin Stagg)	User agent configuration support (PR #89)
mattdm (Matthew Miller)	Logging improvements, FORGEJO_* migration, README, URL refactor
byteflavour	check_notifications + full notification management API (PR #84, #86); feature requests #80, #85
jesterret	Pull request reviews and comments support (PR #51)
appleboy	Custom SSE port support, bug fixes
hiifong	Early bug fixes and updates
Lunny Xiao	Early contributions
techknowlogick	Early contributions
yp05327	Early contributions
mw75	Owner/org support for repo creation (PR #18)
Dax Kelson	Issue comment management (PR #34)
Guruprasad Kulkarni	Arch Linux AUR installation docs (PR #69)
Mario Wolff	Contributions
Massimo Fraschetti	Contributions

Community contributors

Issue reporters and discussion participants who shaped the direction of the project:

Contributor	Contributions
byteflavour	Filed #80 (milestone/label discovery), #85 (notification API proposal); active reviewer in discussions
choucavalier	Filed #82 (fix skill), #70 (macOS arm64 releases), #62 (binary releases & mise support)
MalcolmMielle	Filed #59 (PR review tools — since implemented)
redbeard	Filed #60 (Actions support — since implemented)
c6sepl6p	Filed #72 (base64 encoding), #54 (merge pull request — since implemented)
malik	Filed #73 (version flag), #47 (Nix build fix)
a2800276	Filed #74 (OpenAI compatibility)
simenandre	Filed #49 (go install support)
BasdP	Filed #42 (Projects support)
BoBeR182	Filed #32 (wiki support)
fraschm98	Early issue reports

Cyborg contributors

This project also received contributions from AI coding agents — submitted as regular PRs, reviewed by humans:

Agent	Role	Contributions
brenner-axiom (b4-dev, B4arena)	AI dev agent	list_repo_milestones, list_repo_labels tools (PR #83); race condition fix (PR #78); contributors docs (PR #87, #88); filed #76; code reviews
b4mad-release-bot	Release automation	Automated changelog and release tagging
the #B4mad Renovate bot	Dependency updates	Automated dependency upgrades

Want to contribute? Open an issue or pull request — all are welcome.

License

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