Gitea MCP Server

A production-ready Model Context Protocol (MCP) server for seamless integration with self-hosted Gitea platforms. This server provides tools for creating repositories and uploading files while preserving directory structure.

Installation and Setup Guide

This guide provides step-by-step instructions for installing and configuring the Gitea MCP server, including troubleshooting common issues.

Features

• Repository Creation: Create new repositories on any configured Gitea instance
• File Upload: Upload files and folders while preserving directory structure
• Project Sync: Automatically sync entire projects for initial commits (new files only)
• Advanced File Updates: Smart update tool with conflict resolution for modifying existing files
• Multi-Instance Support: Connect to multiple Gitea instances simultaneously
• Rate Limiting: Respect API rate limits per instance
• Batch Processing: Efficient file upload with configurable batch sizes
• Comprehensive Logging: Structured logging with security-safe output
• Error Handling: Robust error handling with retry logic
• TypeScript: Full type safety and modern JavaScript features

Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• Access to one or more Gitea instances
• Personal access tokens for authentication

Installation

1. Clone the repository:

git clone <repository-url>
cd gitea-mcp

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env
# Edit .env with your Gitea instance details

4. Build the project:

npm run build

5. Start the server:

npm run start:mcp

Troubleshooting Common Issues

Windows Compatibility

If you're running on Windows, you might encounter issues with the build script. The default build script uses the chmod command, which is not available on Windows. The package.json has been updated to use a Windows-compatible build script.

Logging Configuration

If you encounter issues with the logging configuration, make sure you have the pino-pretty package installed:

npm install --save-dev pino-pretty

Environment Variables

The .env file should contain the following configuration:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=debug

# Gitea Configuration
# Replace with your Gitea instance URL and token
GITEA_INSTANCES=[{"id":"main","name":"Main Gitea Instance","baseUrl":"https://your-gitea-instance.com","token":"your-personal-access-token","timeout":30000,"rateLimit":{"requests":100,"windowMs":60000}}]

# Upload Configuration
MAX_FILE_SIZE=10485760
MAX_FILES=100
BATCH_SIZE=10

# Gitea API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Make sure to replace "https://your-gitea-instance.com" with your actual Gitea instance URL and "your-personal-access-token" with your Gitea personal access token.

Running with Debug Logging

To run the server with debug logging enabled, use the start:mcp script:

npm run start:mcp

This script sets the NODE_ENV to development and LOG_LEVEL to debug before starting the server.

Development Setup

For development with hot reloading:

npm run dev

Configuration

Environment Variables

Create a .env file based on .env.example:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=info

# Gitea Configuration
GITEA_INSTANCES='[
  {
    "id": "main",
    "name": "Main Gitea Instance", 
    "baseUrl": "https://gitea.example.com",
    "token": "your-personal-access-token",
    "timeout": 30000,
    "rateLimit": {
      "requests": 100,
      "windowMs": 60000
    }
  }
]'

# Upload Configuration
MAX_FILE_SIZE=10485760  # 10MB
MAX_FILES=100
BATCH_SIZE=10

# API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Gitea Instance Configuration

Each Gitea instance requires:

• id: Unique identifier for the instance
• name: Human-readable name for logging
• baseUrl: Base URL of your Gitea instance
• token: Personal access token with appropriate permissions
• timeout: Request timeout in milliseconds (optional)
• rateLimit: Rate limiting configuration (optional)

Personal Access Token Setup

1. Log into your Gitea instance
2. Go to Settings → Applications → Personal Access Tokens
3. Create a new token with these permissions:
   • repo: Full repository access
   • write:repository: Create repositories
   • read:user: Read user information

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/gitea-mcp",
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Other MCP Clients

The server communicates via stdio and follows the MCP protocol specification. Refer to your client's documentation for configuration details.

Available Tools

create_repository

Create a new repository on a specified Gitea instance.

Parameters:

• instanceId (string, required): Gitea instance identifier
• name (string, required): Repository name
• description (string, optional): Repository description
• private (boolean, default: true): Make repository private
• autoInit (boolean, default: true): Initialize with README
• defaultBranch (string, default: "main"): Default branch name

Example:

{
  "instanceId": "main",
  "name": "my-new-repo",
  "description": "A test repository",
  "private": true,
  "autoInit": true,
  "defaultBranch": "main"
}

upload_files

Upload multiple files to a repository while preserving directory structure.

Parameters:

• instanceId (string, required): Gitea instance identifier
• owner (string, required): Repository owner username
• repository (string, required): Repository name
• files (array, required): Array of file objects with path and content
• message (string, required): Commit message
• branch (string, default: "main"): Target branch
• batchSize (number, default: 10): Files per batch

Example:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-repo",
  "files": [
    {
      "path": "README.md",
      "content": "# My Project\n\nProject description here."
    },
    {
      "path": "src/index.js", 
      "content": "console.log('Hello, World!');"
    }
  ],
  "message": "Initial commit",
  "branch": "main",
  "batchSize": 5
}

sync_project ⚠️ Initial Commits Only

Automatically discover and sync an entire project directory to a Gitea repository while respecting .gitignore rules.

Important: This tool is designed for initial project uploads and can only create new files. It cannot update files that already exist in the repository. For updating existing files, use the sync_update tool instead.

Parameters:

• instanceId (string, required): Gitea instance identifier
• owner (string, required): Repository owner username
• repository (string, required): Repository name
• message (string, required): Commit message for the sync
• branch (string, default: "main"): Target branch
• projectPath (string, default: "."): Path to project directory to sync
• dryRun (boolean, default: false): Preview what would be uploaded without actually uploading
• includeHidden (boolean, default: false): Include hidden files (starting with .)
• maxFileSize (number, default: 1048576): Maximum file size in bytes (1MB)
• textOnly (boolean, default: true): Only upload text files (skip binary files)

Features:

• Automatically reads and applies .gitignore rules
• Includes sensible defaults for common ignore patterns (node_modules/, .git/, etc.)
• Recursively scans project directory for eligible files
• Simple heuristic to detect and optionally skip binary files
• Size filtering for large files
• Dry run mode for previewing changes
• Detailed reporting of discovered, filtered, uploaded, and failed files

Use Cases:

• Initial project setup and first commit
• Uploading new projects to empty repositories
• Bulk upload of files to new repositories

Example:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "message": "Initial project sync",
  "branch": "main",
  "projectPath": "./my-app",
  "dryRun": false,
  "includeHidden": false,
  "maxFileSize": 2097152,
  "textOnly": true
}

sync_update ✨ Advanced File Updates

Advanced tool for updating existing files in Gitea repository with intelligent conflict resolution and change detection.

Parameters:

• instanceId (string, required): Gitea instance identifier
• owner (string, required): Repository owner username
• repository (string, required): Repository name
• files (array, required): Array of file operation objects
• files[].path (string, required): File path in repository (forward slashes)
• files[].content (string, conditional): File content (required for add/modify operations)
• files[].operation (string, required): Operation type: 'add', 'modify', or 'delete'
• files[].sha (string, optional): Current file SHA (auto-detected if not provided)
• message (string, required): Commit message for all operations
• branch (string, default: "main"): Target branch
• strategy (string, default: "auto"): Update strategy: 'auto', 'batch', or 'individual'
• conflictResolution (string, default: "fail"): Conflict handling: 'fail', 'overwrite', or 'skip'
• detectChanges (boolean, default: true): Compare with remote files to