Contents

Table of Contents

Installation Guide

Prerequisites
Install

npx (no install)
Clone and Build
Docker (SSE mode)
Verify the Build

MokoGitea Token Generation
Configuration

Environment Variables (simplest)
Config File Format
Config Fields
Custom Config Path
File Permissions

Claude Code Registration

npx (recommended)
Local Build

Troubleshooting

"Failed to load config" Error
"Connection not found" Error
Authentication Failures (HTTP 401)
TLS / Certificate Errors
Timeout Errors
MCP Server Not Appearing in Claude Code

← Home

Installation Guide

Prerequisites

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

Install

npx (no install)

GITEA_URL=https://gitea.example.com GITEA_TOKEN=your_token npx @mokoconsulting/mokogitea-mcp

Clone and Build

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

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

Docker (SSE mode)

docker run -p 3100:3100 \
  -e GITEA_URL=https://gitea.example.com \
  -e GITEA_TOKEN=your_token \
  mokoconsulting/mokogitea-mcp

Connect MCP client to http://localhost:3100/sse.

Verify the Build

node dist/index.js --help

MokoGitea Token Generation

Log in to your MokoGitea instance (e.g., https://git.mokoconsulting.tech)
Navigate to Settings (click your avatar, top-right corner)
Select Applications from the sidebar
Under Manage Access Tokens, enter a descriptive token name (e.g., mcp-server)
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
Click Generate Token
Copy the token immediately -- it will not be displayed again

Configuration

Environment Variables (simplest)

GITEA_URL=https://gitea.example.com GITEA_TOKEN=your_token

Config File Format

Create ~/.mcp_mokogitea.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 MokoGitea instance (no trailing slash)
`connections.<name>.token`	string	Yes	MokoGitea 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 ~/.mcp_mokogitea.json

Claude Code Registration

npx (recommended)

Add to .claude.json:

{
  "mcpServers": {
    "mokogitea": {
      "command": "npx",
      "args": ["@mokoconsulting/mokogitea-mcp"],
      "env": {
        "GITEA_URL": "https://gitea.example.com",
        "GITEA_TOKEN": "your_token"
      }
    }
  }
}

Local Build

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

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

Troubleshooting

"Failed to load config" Error

Verify ~/.mcp_mokogitea.json exists and is valid JSON
Or set GITEA_URL and GITEA_TOKEN environment variables
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 MokoGitea instance
Confirm the MokoGitea instance has API access enabled (admin setting)

TLS / Certificate Errors

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

Timeout Errors

The default request timeout is 30 seconds
Check network connectivity to the MokoGitea instance
Verify the MokoGitea 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

Repo: mcp-mokogitea-api . MokoStandards

Revision	Date	Author	Description
1.1	2026-06-18	Moko Consulting	Update repo name, add npx/Docker install, env var config
1.0	2026-05-09	Moko Consulting	Initial version

Pages