🔧 forgejo-mcp

MCP Server for comprehensive Forgejo API integration - featuring repository management, issue tracking, pull requests, labels, milestones, releases, and full testing capabilities.

Features

Repository Operations

• 📋 list_repos - List all repositories with pagination
• 🔍 get_repo - Get repository details

Issue Management

• 📝 list_issues - List issues with state filter and pagination
• ➕ create_issue - Create new issue with labels and milestone
• 💬 comment_issue - Add comment to issue
• ✅ close_issue - Close an issue

Pull Request Operations

• 🔀 list_prs - List pull requests with state filter and pagination
• ➕ create_pr - Create pull request
• ✅ merge_pr - Merge pull request

🏷️ Label Management

• 📋 list_labels - List repository labels with pagination
• ➕ create_label - Create new labels with color and description

🎯 Milestone Management

• 📋 list_milestones - List milestones with state filter and pagination
• ➕ create_milestone - Create milestones with due dates

🚀 Release Management

• 📋 list_releases - List repository releases with pagination
• ➕ create_release - Create releases with tags, draft/prerelease support

Installation

npm install @customable/forgejo-mcp

Or install from Forgejo Package Registry:

# Add to your .npmrc
echo "@customable:registry=https://git.customable.host/api/packages/customable-mcp/npm/" >> .npmrc

# Install
npm install @customable/forgejo-mcp

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "forgejo-mcp": {
      "command": "node",
      "args": ["/path/to/node_modules/@customable/forgejo-mcp/dist/index.js"],
      "env": {
        "FORGEJO_URL": "https://git.customable.host",
        "FORGEJO_TOKEN": "your-token-here"
      }
    }
  }
}

Environment Variables

• FORGEJO_URL - Your Forgejo instance URL (e.g., https://git.customable.host)
• FORGEJO_TOKEN - Personal Access Token with appropriate permissions

Usage

Once configured, the MCP server will be available in Claude Code. You can use tools like:

list_repos, get_repo, list_issues, create_issue, list_labels, create_label,
list_milestones, create_milestone, list_releases, create_release, etc.

Examples

List issues with pagination

{
  "tool": "list_issues",
  "arguments": {
    "owner": "customable-mcp",
    "repo": "forgejo-mcp",
    "state": "open",
    "page": 1,
    "limit": 30
  }
}

Create issue with labels and milestone

{
  "tool": "create_issue",
  "arguments": {
    "owner": "customable-mcp",
    "repo": "forgejo-mcp",
    "title": "Add new feature",
    "body": "Feature description",
    "labels": ["enhancement", "high-priority"],
    "milestone": 1
  }
}

Create label

{
  "tool": "create_label",
  "arguments": {
    "owner": "customable-mcp",
    "repo": "forgejo-mcp",
    "name": "bug",
    "color": "ff0000",
    "description": "Bug reports"
  }
}

Create milestone with due date

{
  "tool": "create_milestone",
  "arguments": {
    "owner": "customable-mcp",
    "repo": "forgejo-mcp",
    "title": "v2.0.0",
    "description": "Major release",
    "dueOn": "2025-12-31T23:59:59Z"
  }
}

Create release

{
  "tool": "create_release",
  "arguments": {
    "owner": "customable-mcp",
    "repo": "forgejo-mcp",
    "tagName": "v2.0.0",
    "name": "Version 2.0.0",
    "body": "Release notes here",
    "draft": false,
    "prerelease": false,
    "targetCommitish": "main"
  }
}

What's New in v2.0.0

🎉 Major release with comprehensive improvements:

• 🏗️ Complete refactor - Modular architecture (376 lines → 97 lines in index.ts, -74%)
• 🔒 100% type safety - Eliminated all any types
• 🧪 Full test suite - 48 unit tests with Vitest
• 📝 Complete JSDoc - All public APIs documented
• ✨ 6 new tools - Labels, milestones, releases management
• ⚡ Enhanced pagination - Consistent pagination across all endpoints
• 📦 Updated dependencies - MCP SDK 1.20.0 (latest)

See CHANGELOG.md for full details.

API Reference

Forgejo API: /api/v1

License

MIT