forgejo-mcp

A Model Context Protocol (MCP) server for Forgejo that enables AI agents to interact with a Forgejo instance as an authenticated user.

Features

Tool	Forgejo API endpoint	Description
search_issues	GET /api/v1/repos/issues/search	Search issues & PRs across all repos
list_issues	GET /api/v1/repos/{owner}/{repo}/issues	List issues in a repository
get_issue	GET /api/v1/repos/{owner}/{repo}/issues/{index}	Get a single issue
create_issue	POST /api/v1/repos/{owner}/{repo}/issues	Create a new issue
edit_issue	PATCH /api/v1/repos/{owner}/{repo}/issues/{index}	Edit an issue
list_issue_comments	GET /api/v1/repos/{owner}/{repo}/issues/{index}/comments	List comments
create_comment	POST /api/v1/repos/{owner}/{repo}/issues/{index}/comments	Add a comment
search_repos	GET /api/v1/repos/search	Search repositories
get_repo	GET /api/v1/repos/{owner}/{repo}	Get repository info
get_user	GET /api/v1/user	Get authenticated user profile
get_user_info	GET /api/v1/users/{username}	Get any user's public profile
list_notifications	GET /api/v1/notifications	List notifications
list_pull_requests	GET /api/v1/repos/{owner}/{repo}/pulls	List pull requests in a repository
get_pull_request	GET /api/v1/repos/{owner}/{repo}/pulls/{index}	Get a single pull request
create_pull_request	POST /api/v1/repos/{owner}/{repo}/pulls	Create a new pull request
edit_pull_request	PATCH /api/v1/repos/{owner}/{repo}/pulls/{index}	Edit a pull request
merge_pull_request	POST /api/v1/repos/{owner}/{repo}/pulls/{index}/merge	Merge a pull request
get_pull_request_diff	GET /api/v1/repos/{owner}/{repo}/pulls/{index}.diff	Get PR diff as plain text
get_pull_request_files	GET /api/v1/repos/{owner}/{repo}/pulls/{index}/files	List files changed in a PR
list_pull_request_reviews	GET /api/v1/repos/{owner}/{repo}/pulls/{index}/reviews	List reviews on a PR
update_pull_request_branch	POST /api/v1/repos/{owner}/{repo}/pulls/{index}/update	Update a PR branch

Requirements

• Node.js ≥ 18
• A Forgejo personal access token

Installation

npm install -g @openmanbo/forgejo-mcp

Setup

1. Generate a Forgejo token:
   Go to <your-forgejo-instance>/user/settings/applications and create a token with the scopes you need (at minimum read:issue for searching).

2. Configure environment variables:

   export FORGEJO_URL=https://codeberg.org   # or your own instance
   export FORGEJO_TOKEN=your_token_here
   

Running the server

forgejo-mcp
# or with npx (no install needed):
npx @openmanbo/forgejo-mcp

The server communicates over stdio using the MCP protocol.

Connecting to an MCP client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "forgejo": {
      "command": "npx",
      "args": ["-y", "@openmanbo/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://codeberg.org",
        "FORGEJO_TOKEN": "your_token_here"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "forgejo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@openmanbo/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://codeberg.org",
        "FORGEJO_TOKEN": "${env:FORGEJO_TOKEN}"
      }
    }
  }
}

Development

git clone https://github.com/openmanbo/forgejo-mcp.git
cd forgejo-mcp
npm install
npm run build
npm test        # run unit tests

License

MIT