Labsco
MushroomFleet logo

Gitea MCP Server

★ 11

from MushroomFleet

A server for seamless integration with self-hosted Gitea platforms, allowing management of repositories and other resources.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#devops#git#security#monitoring#translation

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.

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

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:

Copy & paste — that's it
{
 "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:

Copy & paste — that's it
{
 "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:

Copy & paste — that's it
{
 "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:

Copy & paste — that's it
{
 "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:

Copy & paste — that's it
{
 "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:

  • create_repository: Create new repositories

  • sync_project: Initial project upload to empty/new repositories

  • upload_files: Upload specific files with full control over the process

  • sync_update: Update existing files, create new files, or delete files in existing repositories

Workflow Example:

Copy & paste — that's it
# 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

Copy & paste — that's it
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

  • Create tool implementation in src/tools/

  • Add schema validation in src/tools/schemas.ts

  • Register tool in src/tools/index.ts

  • Add tests in tests/unit/tools/

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

Contributing

  • Fork the repository

  • Create a feature branch

  • Make changes with tests

  • Run linting and type checking

  • 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.

See Also