# gitea-api-mcp [](https://www.gnu.org/licenses/gpl-3.0) [](https://modelcontextprotocol.io) [](https://nodejs.org) [](https://www.typescriptlang.org) > 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](#background) - [Install](#install) - [Configuration](#configuration) - [Usage](#usage) - [Tools](#tools) - [Contributing](#contributing) - [License](#license) - [Revision History](#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 ```bash 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`: ```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 ```json { "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`): ```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](CONTRIBUTING.md) for development guidelines. ## License [GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0.html) -- Copyright (C) 2026 Moko Consulting ## Revision History | Version | Date | Description | |---------|------|-------------| | 0.0.1 | 2026-05-07 | Initial release with 61 tools |