mcp-server-forgejo

MCP server for Forgejo and Gitea instances — 31 tools for repositories, issues, PRs, CI/CD, and more.

Features

31 tools across 10 categories:

Category	Tools	Description
Repositories	6	List, get, create, fork, delete, search
Issues	6	CRUD, comments
Pull Requests	5	List, get, create, merge, diff
Files	4	Read, write, delete, directory listing
Branches	6	CRUD, commits, compare
CI/CD Actions	5	Workflow runs, jobs, logs, triggers, status monitoring
Releases	4	List, get, create, delete
Users & Orgs	5	User info, organizations, org repos
Search	2	Issues, users
Notifications	3	List, mark read

Production-grade:

• Configurable timeouts and retries with exponential backoff
• Rate limiting awareness
• Structured error handling with differentiated error types
• Built on the modern McpServer API with Zod schema validation

Quick Start

git clone https://edp.buildth.ing/DevFW-CICD/mcp-server-forgejo.git
cd mcp-server-forgejo
npm install
npm run build

Run directly with tsx (development):

FORGEJO_URL=https://your-instance.com FORGEJO_TOKEN=your-token npm run dev

Run compiled (production):

FORGEJO_URL=https://your-instance.com FORGEJO_TOKEN=your-token node dist/index.js

Configuration

Variable	Required	Default	Description
FORGEJO_URL	✅	—	Base URL of your Forgejo/Gitea instance
FORGEJO_TOKEN	✅	—	Personal access token
FORGEJO_TIMEOUT	❌	30000	Request timeout in milliseconds
FORGEJO_MAX_RETRIES	❌	3	Max retry attempts for failed requests
FORGEJO_PAGE_SIZE	❌	30	Default page size for list operations
FORGEJO_VERIFY_SSL	❌	true	Verify SSL certificates (set false for self-signed)

OpenCode Integration

Add to ~/.config/opencode/opencode.json under the "mcp" key.

Using tsx (no build step needed):

{
  "mcp": {
    "forgejo": {
      "enabled": true,
      "type": "local",
      "command": ["npx", "tsx", "/path/to/mcp-server-forgejo/src/index.ts"],
      "environment": {
        "FORGEJO_URL": "https://your-forgejo-instance.com",
        "FORGEJO_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Using compiled output:

{
  "mcp": {
    "forgejo": {
      "enabled": true,
      "type": "local",
      "command": ["node", "/path/to/mcp-server-forgejo/dist/index.js"],
      "environment": {
        "FORGEJO_URL": "https://your-forgejo-instance.com",
        "FORGEJO_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Tip: opencode supports {env:VAR_NAME} syntax to reference host environment variables instead of hardcoding secrets:

"environment": {
  "FORGEJO_URL": "{env:FORGEJO_URL}",
  "FORGEJO_TOKEN": "{env:FORGEJO_TOKEN}"
}

Tool Reference

Repositories

Tool	Description
list_repositories	List repositories for a user or the authenticated user
get_repository	Get details of a specific repository
create_repository	Create a new repository
fork_repository	Fork a repository
delete_repository	Delete a repository
search_repositories	Search repositories by keyword

Issues

Tool	Description
list_issues	List issues in a repository
get_issue	Get a specific issue by number
create_issue	Create a new issue
edit_issue	Edit an existing issue
list_issue_comments	List comments on an issue
create_issue_comment	Add a comment to an issue

Pull Requests

Tool	Description
list_pull_requests	List pull requests in a repository
get_pull_request	Get a specific pull request
create_pull_request	Create a new pull request
merge_pull_request	Merge a pull request
get_pull_request_diff	Get the diff of a pull request

Files

Tool	Description
get_file_content	Get file content (base64 decoded)
create_or_update_file	Create or update a file in a repository
delete_file	Delete a file from a repository
get_directory_contents	List contents of a directory

Branches

Tool	Description
list_branches	List branches in a repository
get_branch	Get details of a specific branch
create_branch	Create a new branch
delete_branch	Delete a branch
list_commits	List commits on a branch
compare_commits	Compare two commits or branches

CI/CD Actions

Tool	Description
list_workflow_runs	List workflow runs for a repository
get_workflow_run	Get details of a workflow run
list_workflow_run_jobs	List jobs for a workflow run (name, status, duration, steps)
get_workflow_run_log	Fetch raw log output for a specific job in a workflow run
trigger_workflow	Trigger a workflow dispatch event

Releases

Tool	Description
list_releases	List releases in a repository
get_release	Get a specific release
create_release	Create a new release
delete_release	Delete a release

Users & Organizations

Tool	Description
get_authenticated_user	Get the currently authenticated user
get_user	Get a user by username
list_organizations	List organizations for the authenticated user
get_organization	Get organization details
list_organization_repos	List repositories in an organization

Search

Tool	Description
search_issues	Search issues and PRs across repositories
search_users	Search users by keyword

Notifications

Tool	Description
list_notifications	List notifications for the authenticated user
mark_notifications_read	Mark all notifications as read
mark_thread_read	Mark a specific notification thread as read

Compatibility

Platform	Support
Forgejo	Full support including Actions CI/CD
Gitea	Full support — API is compatible

All tools use standard /api/v1 endpoints. Self-hosted forks with customized endpoints (webhooks, etc.) should work as long as the core API remains unchanged.

Development

npm run dev       # Run with tsx (hot reload)
npm run build     # Compile TypeScript
npm run test      # Run tests
npm run lint      # Lint

Architecture

src/
├── index.ts        — Entry point, MCP server setup
├── client.ts       — HTTP client (retries, timeouts, error differentiation)
├── tools/          — One file per domain, individual tool registration
└── types/          — TypeScript types for Forgejo API responses

• Modern McpServer API with registerTool pattern
• Native Zod validation for all tool inputs
• Structured error responses with HTTP status differentiation

Token Permissions

Your personal access token needs these scopes:

Scope	Required For
repo	Repositories, files, branches, PRs, releases
issue	Issues and comments
notification	Notifications
user	User information
admin:org	Organization operations

Generate a token at https://your-instance.com/user/settings/applications.

License

MIT