mcp-mokogitea-api/README.md

<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
DEFGROUP: gitea-api-mcp.Documentation
REPO: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp
-->

# gitea-api-mcp

[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![MCP](https://img.shields.io/badge/MCP-compatible-brightgreen.svg)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-green.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](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 |