gitea-api-mcp

MCP server for Gitea REST API v1 operations -- 61 tools for complete Gitea instance management from Claude Code and other MCP clients.

Table of Contents

• Background
• Install
• Configuration
• Usage
• Tools
• Contributing
• License
• Revision History

Background

gitea-api-mcp is a Model Context Protocol (MCP) server that exposes 61 tools for interacting with the Gitea REST API v1. It supports multiple named connections, allowing you to manage several Gitea instances from a single server. Authentication uses Gitea's native Authorization: token header format.

Install

Prerequisites

• Node.js >= 20.0.0
• A Gitea instance with API access
• A Gitea access token (Settings > Applications > Generate Token)

Build from Source

git clone https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp.git
cd gitea-api-mcp
npm install
npm run build

Configuration

Create ~/.gitea-api-mcp.json:

{
  "defaultConnection": "moko",
  "connections": {
    "moko": {
      "baseUrl": "https://git.mokoconsulting.tech",
      "token": "your-gitea-access-token",
      "insecure": false
    }
  }
}

Config Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | baseUrl | string | Yes | Base URL of your Gitea instance | | token | string | Yes | Gitea API access token | | insecure | boolean | No | Skip TLS verification (self-signed certs) |

Override the config path with the GITEA_API_MCP_CONFIG environment variable.

Multi-Connection Example

{
  "defaultConnection": "moko",
  "connections": {
    "moko": {
      "baseUrl": "https://git.mokoconsulting.tech",
      "token": "token-for-moko-gitea"
    },
    "github-mirror": {
      "baseUrl": "https://gitea.example.com",
      "token": "token-for-mirror"
    }
  }
}

Usage

Claude Code Registration

Add to your Claude Code MCP config (~/.claude/claude_desktop_config.json or project-level .mcp.json):

{
  "mcpServers": {
    "gitea-moko": {
      "command": "node",
      "args": ["/path/to/gitea-api-mcp/dist/index.js"]
    }
  }
}

Multi-Connection Usage in Claude Code

When using multiple connections, pass the connection parameter to any tool:

Use gitea_repo_get with connection "github-mirror" to get owner/repo details.

If connection is omitted, the defaultConnection is used.

Tools

User / Auth (3 tools)

| Tool | Description | |------|-------------| | gitea_me | Get the authenticated user info | | gitea_user_orgs | List organizations the authenticated user belongs to | | gitea_user_repos | List repositories owned by the authenticated user |

Repositories (8 tools)

| Tool | Description | |------|-------------| | gitea_repo_get | Get repository details | | gitea_repo_create | Create a new repository | | gitea_repo_delete | Delete a repository | | gitea_repo_edit | Edit repository settings | | gitea_repo_fork | Fork a repository | | gitea_repo_search | Search repositories | | gitea_org_repos | List repositories in an organization | | gitea_list_connections | List configured Gitea connections |

File Contents (5 tools)

| Tool | Description | |------|-------------| | gitea_file_get | Get file contents from a repository | | gitea_dir_get | Get directory contents (file listing) from a repository | | gitea_file_create_or_update | Create or update a file in a repository | | gitea_file_delete | Delete a file from a repository | | gitea_tree_get | Get the git tree for a repository (recursive file listing) |

Branches (4 tools)

| Tool | Description | |------|-------------| | gitea_branches_list | List branches in a repository | | gitea_branch_get | Get a specific branch | | gitea_branch_create | Create a new branch | | gitea_branch_delete | Delete a branch |

Commits (2 tools)

| Tool | Description | |------|-------------| | gitea_commits_list | List commits in a repository | | gitea_commit_get | Get a specific commit |

Issues (7 tools)

| Tool | Description | |------|-------------| | gitea_issues_list | List issues in a repository | | gitea_issue_get | Get a single issue by number | | gitea_issue_create | Create a new issue | | gitea_issue_update | Update an issue | | gitea_issue_comments_list | List comments on an issue | | gitea_issue_comment_create | Add a comment to an issue | | gitea_issue_search | Search issues across all repositories |

Labels (2 tools)

| Tool | Description | |------|-------------| | gitea_labels_list | List labels in a repository | | gitea_label_create | Create a label |

Milestones (2 tools)

| Tool | Description | |------|-------------| | gitea_milestones_list | List milestones in a repository | | gitea_milestone_create | Create a milestone |

Pull Requests (6 tools)

| Tool | Description | |------|-------------| | gitea_pulls_list | List pull requests | | gitea_pull_get | Get a single pull request | | gitea_pull_create | Create a pull request | | gitea_pull_merge | Merge a pull request | | gitea_pull_files | List files changed in a pull request | | gitea_pull_review_create | Create a pull request review |

Releases (5 tools)

| Tool | Description | |------|-------------| | gitea_releases_list | List releases | | gitea_release_get | Get a single release by ID | | gitea_release_latest | Get the latest release | | gitea_release_create | Create a new release | | gitea_release_delete | Delete a release |

Tags (3 tools)

| Tool | Description | |------|-------------| | gitea_tags_list | List tags | | gitea_tag_create | Create a tag | | gitea_tag_delete | Delete a tag |

Actions (2 tools)

| Tool | Description | |------|-------------| | gitea_actions_runs_list | List workflow runs for a repository | | gitea_actions_run_get | Get a specific workflow run |

Organizations (3 tools)

| Tool | Description | |------|-------------| | gitea_org_get | Get organization details | | gitea_org_teams_list | List teams in an organization | | gitea_org_members_list | List members of an organization |

Users (2 tools)

| Tool | Description | |------|-------------| | gitea_user_get | Get a user profile | | gitea_users_search | Search users |

Webhooks (2 tools)

| Tool | Description | |------|-------------| | gitea_webhooks_list | List webhooks for a repository | | gitea_webhook_create | Create a webhook |

Wiki (2 tools)

| Tool | Description | |------|-------------| | gitea_wiki_pages_list | List wiki pages | | gitea_wiki_page_get | Get a wiki page |

Notifications (2 tools)

| Tool | Description | |------|-------------| | gitea_notifications_list | List notifications for the authenticated user | | gitea_notifications_read | Mark all notifications as read |

Generic (2 tools)

| Tool | Description | |------|-------------| | gitea_api_request | Make a raw API request to any Gitea v1 endpoint | | gitea_list_connections | List configured Gitea connections |

Contributing

See CONTRIBUTING.md for development guidelines.

License

GPL-3.0-or-later -- Copyright (C) 2026 Moko Consulting

Revision History

| Version | Date | Description | |---------|------|-------------| | 0.0.1 | 2026-05-07 | Initial release with 61 tools |