mcp-mokogitea-api/docs/INSTALLATION.md

Installation Guide

Prerequisites

• Node.js >= 20.0.0 (download)
• npm (included with Node.js)
• A Gitea instance with API access enabled
• A Gitea access token with appropriate scopes

Install

Clone and Build

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

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:

{
  "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:

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

File Permissions

Secure your config file since it contains API tokens:

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

Claude Code Registration

Project-Level (.mcp.json)

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

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

Global-Level (~/.claude/claude_desktop_config.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