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 avoid unnecessary updates
• dryRun (boolean, default: false): Preview operations without making changes

Key Features:

• Smart API Usage: Uses PUT for updates, POST for creates, DELETE for removals
• Change Detection: Compares local vs remote content to skip unnecessary updates
• Auto SHA Resolution: Automatically fetches required SHA values for update operations
• Multiple Strategies: Auto, batch (single commit), or individual (separate commits)
• Conflict Resolution: Handles cases where remote files have changed since last sync
• Mixed Operations: Can handle create, update, and delete operations in a single call
• Dry Run Mode: Preview what operations would be performed without making changes

Operation Types:

• add: Create new files (equivalent to POST API)
• modify: Update existing files (uses PUT API with SHA for conflict resolution)
• delete: Remove existing files (uses DELETE API with SHA)

Strategy Options:

• auto: Intelligently chooses the best approach based on file count and operation types
• batch: Performs all operations in a single commit using Gitea's batch API
• individual: Performs each operation as a separate commit

Use Cases:

• Updating existing project files
• Selective file modifications
• Bulk file operations (create, update, delete)
• Incremental project updates
• Automated file maintenance

Example:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "files": [
    {
      "path": "README.md",
      "content": "# Updated Project\n\nThis is an updated version of the project.",
      "operation": "modify"
    },
    {
      "path": "src/new-feature.js",
      "content": "// New feature implementation\nfunction newFeature() {\n  return 'Hello, World!';\n}",
      "operation": "add"
    },
    {
      "path": "old-file.txt",
      "operation": "delete"
    }
  ],
  "message": "Update documentation and add new feature",
  "branch": "main",
  "strategy": "auto",
  "detectChanges": true,
  "dryRun": false
}

Dry Run Example Response:

{
  "dryRun": true,
  "strategy": "individual",
  "summary": {
    "discovered": 3,
    "analyzed": 3,
    "needsUpdate": 2,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "skipped": 0
  },
  "filesNeedingUpdate": [
    {
      "path": "README.md",
      "operation": "modify",
      "hasRemoteSha": true
    },
    {
      "path": "src/new-feature.js",
      "operation": "add",
      "hasRemoteSha": false
    }
  ]
}

Tool Selection Guide

When to use each tool:

1. create_repository: Create new repositories
2. sync_project: Initial project upload to empty/new repositories
3. upload_files: Upload specific files with full control over the process
4. sync_update: Update existing files, create new files, or delete files in existing repositories

Workflow Example:

# 1. Create a new repository
create_repository → "my-new-project"

# 2. Initial upload of all project files
sync_project → Upload entire project structure

# 3. Later updates to specific files
sync_update → Modify README.md, add new features, delete old files

Development

Scripts

• npm run build - Build for production
• npm run dev - Development with hot reloading
• npm start - Start production server
• npm test - Run tests
• npm run lint - Lint code
• npm run format - Format code
• npm run type-check - TypeScript type checking

Project Structure

gitea-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config/               # Configuration management
│   ├── gitea/                # Gitea API client
│   ├── tools/                # MCP tool implementations
│   ├── services/             # Business logic services
│   ├── utils/                # Utilities (logging, errors, etc.)
│   └── types/                # TypeScript type definitions
├── build/                    # Compiled JavaScript
├── docs/                     # Documentation
└── package.json

Adding New Tools

1. Create tool implementation in src/tools/
2. Add schema validation in src/tools/schemas.ts
3. Register tool in src/tools/index.ts
4. Add tests in tests/unit/tools/

Deployment

Docker

Build and run with Docker:

# Build image
docker build -t gitea-mcp .

# Run container
docker run -d \
  --name gitea-mcp \
  --env-file .env \
  gitea-mcp

Production Considerations

• Use environment variables or secrets management for tokens
• Configure appropriate log levels
• Set up monitoring and health checks
• Use process managers like PM2 for Node.js applications
• Consider using Docker or Kubernetes for orchestration

Security

Best Practices

• Store tokens securely using environment variables or secrets management
• Use minimal required permissions for access tokens
• Validate all input parameters
• Log security events without exposing sensitive data
• Use HTTPS for all Gitea API communications
• Regularly rotate access tokens

Rate Limiting

The server implements rate limiting per Gitea instance to respect API limits:

• Default: 100 requests per minute per instance
• Configurable via rateLimit in instance configuration
• Automatic retry with exponential backoff

Troubleshooting

Common Issues

Authentication Failed

• Verify access token is correct and has required permissions
• Check token hasn't expired
• Ensure base URL is correct

Rate Limited

• Reduce batch size for file uploads
• Adjust rate limit configuration
• Wait before retrying requests

File Upload Failures

• Check file content is valid
• Verify file paths don't contain illegal characters
• Ensure repository exists and you have write permissions

Logging

Enable debug logging for troubleshooting:

LOG_LEVEL=debug npm start

Health Checks

Check server status:

curl -f http://localhost:8080/health || exit 1

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run linting and type checking
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: Report bugs and feature requests
• Documentation: Check docs/ directory
• Examples: See examples/ directory

---

Built with ❤️ for the Gitea and MCP communities.