<!-- 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
-->

# Installation Guide

## Prerequisites

- **Node.js** >= 20.0.0 ([download](https://nodejs.org))
- **npm** (included with Node.js)
- A **Gitea instance** with API access enabled
- A **Gitea access token** with appropriate scopes

## Install

### Clone and Build

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

The compiled output is placed in `dist/index.js`.

### Verify the Build

```bash
node dist/index.js --help
```

## Gitea Token Generation

1. Log in to your Gitea instance (e.g., `https://git.mokoconsulting.tech`)
2. Navigate to **Settings** (click your avatar, top-right corner)
3. Select **Applications** from the sidebar
4. Under **Manage Access Tokens**, enter a descriptive token name (e.g., `mcp-server`)
5. Select the required permission scopes:
   - `repo` -- for repository operations
   - `admin:org` -- for organization management
   - `notification` -- for notification tools
   - `user` -- for user profile operations
   - `issue` -- for issue and pull request tools
   - `package` -- if using package-related endpoints
6. Click **Generate Token**
7. **Copy the token immediately** -- it will not be displayed again

## Configuration

### Config File Format

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 |
|-------|------|----------|-------------|
| `defaultConnection` | string | No | Name of the default connection (defaults to the first one) |
| `connections` | object | Yes | Map of named connections |
| `connections.<name>.baseUrl` | string | Yes | Base URL of the Gitea instance (no trailing slash) |
| `connections.<name>.token` | string | Yes | Gitea API access token |
| `connections.<name>.insecure` | boolean | No | Skip TLS certificate verification (default: `false`) |

### Custom Config Path

Override the default config location with an environment variable:

```bash
export GITEA_API_MCP_CONFIG=/path/to/custom-config.json
```

### File Permissions

Secure your config file since it contains API tokens:

```bash
chmod 600 ~/.gitea-api-mcp.json
```

## Claude Code Registration

### Project-Level (`.mcp.json`)

Create or edit `.mcp.json` in your project root:

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

### Global-Level (`~/.claude/claude_desktop_config.json`)

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

After registering, restart Claude Code or run `/mcp` to verify the server is connected.

## Troubleshooting

### "Failed to load config" Error

- Verify `~/.gitea-api-mcp.json` exists and is valid JSON
- Check that at least one connection is defined in `connections`
- If using `GITEA_API_MCP_CONFIG`, verify the path is correct and the file is readable

### "Connection not found" Error

- The `connection` parameter you passed does not match any key in `connections`
- Run `gitea_list_connections` to see available connections
- Check for typos in the connection name

### Authentication Failures (HTTP 401)

- Verify your token is correct and has not expired
- Ensure the token has the required scopes for the operation
- Check that the `baseUrl` points to the correct Gitea instance
- Confirm the Gitea instance has API access enabled (admin setting)

### TLS / Certificate Errors

- For self-signed certificates, set `"insecure": true` in the connection config
- Ensure the Gitea instance URL uses the correct protocol (`https://` vs `http://`)

### Timeout Errors

- The default request timeout is 30 seconds
- Check network connectivity to the Gitea instance
- Verify the Gitea instance is running and responsive
- For large responses (e.g., recursive tree listings), consider pagination

### MCP Server Not Appearing in Claude Code

- Ensure the path in your MCP config is an absolute path to `dist/index.js`
- Verify the build completed successfully (`npm run build`)
- Check that Node.js >= 20.0.0 is in your PATH
- Restart Claude Code after modifying MCP configuration