Gitea MCP Server

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

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.

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

- 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

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

git clone <repository-url> cd gitea-mcp

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

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

If you encounter issues with the logging configuration, make sure you have thepino-prettypackage installed:

The.envfile 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.

To run the server with debug logging enabled, use thestart:mcpscript:

This script sets theNODE_ENVtodevelopmentandLOG_LEVELtodebugbefore starting the server.

Create a.envfile 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

- 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)
- Log into your Gitea instance
- Go to Settings → Applications → Personal Access Tokens
- Create a new token with these permissions:

- repo: Full repository access
- write:repository: Create repositories
- read:user: Read user information

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" } } } }

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

Create a new repository on a specified Gitea instance.

- 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

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

Upload multiple files to a repository while preserving directory structure.

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

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

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

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 thesync_updatetool instead.

- 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)

- Automatically reads and applies.gitignorerules
- 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

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

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

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

- 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

- 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

- 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)

- 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

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

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

{ "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 } ] }

- 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

# 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

- 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

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

- Create tool implementation insrc/tools/
- Add schema validation insrc/tools/schemas.ts
- Register tool insrc/tools/index.ts
- Add tests intests/unit/tools/

# Build image docker build -t gitea-mcp . # Run container docker run -d \ --name gitea-mcp \ --env-file .env \ gitea-mcp

- 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

- 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

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

- Default: 100 requests per minute per instance
- Configurable viarateLimitin instance configuration
- Automatic retry with exponential backoff

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

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

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

Enable debug logging for troubleshooting:

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

- Fork the repository
- Create a feature branch
- Make changes with tests
- Run linting and type checking
- Submit a pull request

MIT License - see LICENSE file for details.

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

Built with ❤️ for the Gitea and MCP communities.

- TranscriptionTools-MCP— Transcript processing
- DeepLucid3D-MCP— Cognitive processing
- UNO-MCP— Narrative enhancement
- gitea-mcp— Gitea integration
- zero-vector-MCP— Procedural generation

A Claude Kubernetes MCP server, built in Go. The server integrates with ArgoCD, GitLab, Claude AI, and Kubernetes to enable advanced control and automation of Kubernetes environments.