mcp-servers/forgejo-mcp

Forgejo MCP Server

A comprehensive Model Context Protocol (MCP) server for interacting with a self-hosted Forgejo Git service.

Features

The Forgejo MCP server provides tools for:

• Repository Management: List, create, and inspect repositories
• Issue Tracking: Create, update, list, and manage issues
• Pull Requests: Create and manage pull requests
• Branch Management: List branches and retrieve branch information
• File Operations: Read file contents from repositories
• Search: Search for repositories across the instance
• User Profiles: Get user information and statistics

Configuration

Environment Variables

Variable	Default	Description
FORGEJO_URL	http://10.0.0.25:34577	Forgejo instance URL
FORGEJO_ACCESS_TOKEN	(required)	Forgejo API access token
PORT	8400	Server port
TRANSPORT	http	Transport protocol (http recommended)

Obtaining an Access Token

1. Log in to your Forgejo instance
2. Go to Settings → Applications → Personal Access Tokens
3. Create a new token with the following scopes:
   • repo - Full repository access
   • admin:org_hook (optional) - For webhook management
   • user (optional) - For user profile access

Docker Deployment

The server is containerized and integrated with the MCP gateway docker-compose setup.

Environment File (.env)

Add these variables to your .env file:

# Forgejo Configuration
FORGEJO_URL=http://10.0.0.25:34577
FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83

Docker Compose Integration

The docker-compose.yml includes the Forgejo-MCP service with:

• Container name: mcp-forgejo
• Port: 8400
• Network: mcpnet (internal gateway network)
• Health checks enabled

To start the service:

docker-compose up -d forgejo-mcp

Available Tools

Repository Tools

forgejo_list_repositories

List repositories for a user or organization.

Parameters:

• owner (string, required): Username or organization name
• limit (integer, optional): Max repositories to return (default: 20)
• page (integer, optional): Page number for pagination (default: 1)

forgejo_get_repository

Get details about a specific repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name

forgejo_create_repository

Create a new repository.

Parameters:

• name (string, required): Repository name (lowercase, no spaces)
• description (string, optional): Repository description
• private (boolean, optional): Whether repository is private (default: false)
• auto_init (boolean, optional): Initialize with README (default: true)

Issue Tools

forgejo_list_issues

List issues in a repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• state (string, optional): Filter by state (open, closed, all) (default: open)
• limit (integer, optional): Max issues to return (default: 20)
• page (integer, optional): Page number (default: 1)

forgejo_create_issue

Create a new issue.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• title (string, required): Issue title
• body (string, optional): Issue description (markdown)
• labels (array, optional): Label names

forgejo_update_issue

Update an existing issue.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• issue_number (integer, required): Issue number
• state (string, optional): New state (open, closed)
• title (string, optional): New issue title
• body (string, optional): New issue description

Pull Request Tools

forgejo_list_pull_requests

List pull requests in a repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• state (string, optional): Filter by state (open, closed, all) (default: open)
• limit (integer, optional): Max PRs to return (default: 20)
• page (integer, optional): Page number (default: 1)

forgejo_create_pull_request

Create a new pull request.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• title (string, required): PR title
• body (string, optional): PR description
• head (string, required): Head branch (source)
• base (string, required): Base branch (target)

Branch Tools

forgejo_list_branches

List branches in a repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• limit (integer, optional): Max branches to return (default: 20)
• page (integer, optional): Page number (default: 1)

File Tools

forgejo_get_file

Get file contents from a repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• path (string, required): File path in repository
• ref (string, optional): Branch, tag, or commit SHA (default: main)

Search Tools

forgejo_search_repositories

Search for repositories across the Forgejo instance.

Parameters:

• q (string, required): Search query
• limit (integer, optional): Max results to return (default: 20)
• page (integer, optional): Page number (default: 1)

User Tools

forgejo_get_user

Get user profile information.

Parameters:

• username (string, required): Username

Usage Examples

List all repositories for a user

Tool: forgejo_list_repositories
Parameters:
  owner: "myusername"
  limit: 10

Create a new issue

Tool: forgejo_create_issue
Parameters:
  owner: "myorg"
  repo: "myproject"
  title: "Bug: Login form not responsive"
  body: "The login form breaks on mobile devices"
  labels: ["bug", "high-priority"]

Get repository details

Tool: forgejo_get_repository
Parameters:
  owner: "myorg"
  repo: "myproject"

Read a configuration file

Tool: forgejo_get_file
Parameters:
  owner: "myorg"
  repo: "infrastructure"
  path: "config/production.yml"
  ref: "main"

Error Handling

The server provides detailed error messages:

• Authentication Errors: Check your access token is valid and has required scopes
• Repository Not Found: Verify owner and repository names
• Invalid Parameters: Check parameter types and required fields
• Network Errors: Verify Forgejo URL is accessible

Integration with MCP Gateway

The Forgejo-MCP server is automatically registered with the MCP gateway via the MCP_BACKEND_FORGEJO environment variable. The gateway will:

1. Discover all available tools
2. Register them in the tool registry
3. Route requests to the Forgejo-MCP service
4. Handle authentication and error responses

Development

Building Locally

pip install -r requirements.txt
python3 -m mcp.server.stdio_sse_server forgejo_mcp:server --port 8400

Testing

Use the MCP Inspector to test the server:

npx @modelcontextprotocol/inspector python3 -m mcp.server.stdio_sse_server forgejo_mcp:server

API Documentation

For more information about the Forgejo API, visit: https://forgejo.org/docs/latest/api/

Troubleshooting

"Invalid token" errors

• Verify the token is correct and hasn't expired
• Check token has required scopes (at minimum: repo)
• Try creating a new token with full permissions

"Repository not found"

• Verify the owner and repository names are correct
• Check the user/org has the repository
• Ensure you have access permissions

Connection timeout

• Verify Forgejo URL is correct and accessible
• Check network connectivity to the Forgejo instance
• Verify firewall rules allow the connection

403 Forbidden

• Check token has appropriate scopes
• Verify repository access permissions
• Ensure token hasn't been revoked

Security Considerations

• Token Storage: Store the access token in environment variables or secure configuration
• Network: Use HTTPS in production
• Permissions: Use tokens with minimal required scopes
• Monitoring: Monitor token usage and revoke unused tokens
• Rotation: Periodically rotate access tokens

License

Part of the MCP gateway ecosystem.