Gitea MCP 服务器

一个生产就绪的模型上下文协议 (MCP) 服务器，用于与自托管 Gitea 平台无缝集成。该服务器提供了创建仓库和上传文件（同时保留目录结构）的工具。

安装与设置指南

本指南提供了安装和配置 Gitea MCP 服务器的分步说明，包括常见问题的排查。

Related MCP server: Gitea MCP Tool

功能特性

• 仓库创建：在任何已配置的 Gitea 实例上创建新仓库

• 文件上传：上传文件和文件夹，同时保留目录结构

• 项目同步：自动同步整个项目以进行初始提交（仅限新文件）

• 高级文件更新：带有冲突解决机制的智能更新工具，用于修改现有文件

• 多实例支持：同时连接到多个 Gitea 实例

• 速率限制：遵守每个实例的 API 速率限制

• 批量处理：具有可配置批处理大小的高效文件上传

• 全面日志记录：结构化日志记录，输出安全

• 错误处理：具有重试逻辑的稳健错误处理

• TypeScript：完全的类型安全和现代 JavaScript 特性

快速入门

前置要求

• Node.js 18.0.0 或更高版本

• 访问一个或多个 Gitea 实例

• 用于身份验证的个人访问令牌

安装

1. 克隆仓库：

git clone <repository-url>
cd gitea-mcp

2. 安装依赖：

npm install

3. 配置环境变量：

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

4. 构建项目：

npm run build

5. 启动服务器：

npm run start:mcp

常见问题排查

Windows 兼容性

如果您在 Windows 上运行，可能会遇到构建脚本的问题。默认构建脚本使用 chmod 命令，该命令在 Windows 上不可用。package.json 已更新为使用 Windows 兼容的构建脚本。

日志配置

如果您在日志配置方面遇到问题，请确保已安装 pino-pretty 包：

npm install --save-dev pino-pretty

环境变量

.env 文件应包含以下配置：

# 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

请务必将 "https://your-gitea-instance.com" 替换为您实际的 Gitea 实例 URL，并将 "your-personal-access-token" 替换为您的 Gitea 个人访问令牌。

使用调试日志运行

要以启用调试日志的方式运行服务器，请使用 start:mcp 脚本：

npm run start:mcp

此脚本在启动服务器之前将 NODE_ENV 设置为 development，并将 LOG_LEVEL 设置为 debug。

开发设置

用于热重载的开发环境：

npm run dev

配置

环境变量

基于 .env.example 创建一个 .env 文件：

# 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 实例配置

每个 Gitea 实例需要：

• id：实例的唯一标识符

• name：用于日志记录的人类可读名称

• baseUrl：Gitea 实例的基础 URL

• token：具有适当权限的个人访问令牌

• timeout：请求超时时间（毫秒，可选）

• rateLimit：速率限制配置（可选）

个人访问令牌设置

1. 登录您的 Gitea 实例

2. 转到 设置 → 应用程序 → 个人访问令牌

3. 创建一个具有以下权限的新令牌：

   • repo：完全仓库访问权限

   • write:repository：创建仓库

   • read:user：读取用户信息

MCP 客户端配置

Claude Desktop

添加到您的 Claude Desktop 配置中：

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

其他 MCP 客户端

服务器通过 stdio 进行通信，并遵循 MCP 协议规范。有关配置详情，请参阅您客户端的文档。

可用工具

create_repository

在指定的 Gitea 实例上创建新仓库。

参数：

• instanceId (string, 必填)：Gitea 实例标识符

• name (string, 必填)：仓库名称

• description (string, 可选)：仓库描述

• private (boolean, 默认: true)：将仓库设为私有

• autoInit (boolean, 默认: true)：使用 README 初始化

• defaultBranch (string, 默认: "main")：默认分支名称

示例：

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

upload_files

在保留目录结构的同时，将多个文件上传到仓库。

参数：

• instanceId (string, 必填)：Gitea 实例标识符

• owner (string, 必填)：仓库所有者用户名

• repository (string, 必填)：仓库名称

• files (array, 必填)：包含 path 和 content 的文件对象数组

• message (string, 必填)：提交信息

• branch (string, 默认: "main")：目标分支

• batchSize (number, 默认: 10)：每批次文件数

示例：

{
  "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 ⚠️ 仅限初始提交

自动发现并将整个项目目录同步到 Gitea 仓库，同时遵守 .gitignore 规则。

重要提示：此工具专为初始项目上传而设计，只能创建新文件。它无法更新仓库中已存在的文件。如需更新现有文件，请改用 sync_update 工具。

参数：

• instanceId (string, 必填)：Gitea 实例标识符

• owner (string, 必填)：仓库所有者用户名

• repository (string, 必填)：仓库名称

• message (string, 必填)：同步的提交信息

• branch (string, 默认: "main")：目标分支

• projectPath (string, 默认: ".")：要同步的项目目录路径

• dryRun (boolean, 默认: false)：预览将要上传的内容，而不实际上传

• includeHidden (boolean, 默认: false)：包含隐藏文件（以 . 开头）

• maxFileSize (number, 默认: 1048576)：最大文件大小（字节，1MB）

• textOnly (boolean, 默认: true)：仅上传文本文件（跳过二进制文件）

功能特性：

• 自动读取并应用 .gitignore 规则

• 包含针对常见忽略模式（node_modules/, .git/ 等）的合理默认值

• 递归扫描项目目录以查找符合条件的文件

• 用于检测并可选跳过二进制文件的简单启发式算法

• 大文件大小过滤

• 用于预览更改的试运行模式

• 关于已发现、已过滤、已上传和失败文件的详细报告

使用场景：

• 初始项目设置和首次提交

• 将新项目上传到空仓库

• 将文件批量上传到新仓库

示例：

{
  "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 ✨ 高级文件更新

用于更新 Gitea 仓库中现有文件的高级工具，具有智能冲突解决和更改检测功能。

参数：

• instanceId (string, 必填)：Gitea 实例标识符

• owner (string, 必填)：仓库所有者用户名

• repository (string, 必填)：仓库名称

• files (array, 必填)：文件操作对象数组

• files[].path (string, 必填)：仓库中的文件路径（使用正斜杠）

• files[].content (string, 条件必填)：文件内容（添加/修改操作必需）

• files[].operation (string, 必填)：操作类型：'add'、'modify' 或 'delete'

• files[].sha (string, 可选)：当前文件 SHA（如未提供则自动检测）

• message (string, 必填)：所有操作的提交信息

• branch (string, 默认: "main")：目标分支

• strategy (string, 默认: "auto")：更新策略：'auto'、'batch' 或 'individual'

• conflictResolution (string, 默认: "fail")：冲突处理：'fail'、'overwrite' 或 'skip'

• detectChanges (boolean, 默认: true)：与远程文件比较以避免不必要的更新

• dryRun (boolean, 默认: false)：预览操作而不进行更改

关键特性：

• 智能 API 使用：使用 PUT 进行更新，POST 进行创建，DELETE 进行删除

• 更改检测：比较本地与远程内容以跳过不必要的更新

• 自动 SHA 解析：自动获取更新操作所需的 SHA 值

• 多种策略：自动、批量（单次提交）或单独（多次提交）

• 冲突解决：处理自上次同步以来远程文件已更改的情况

• 混合操作：可以在单次调用中处理创建、更新和删除操作

• 试运行模式：预览将要执行的操作而不进行更改

操作类型：

• add：创建新文件（等同于 POST API）

• modify：更新现有文件（使用带有 SHA 的 PUT API 进行冲突解决）

• delete：删除现有文件（使用带有 SHA 的 DELETE API）

策略选项：

• auto：根据文件数量和操作类型智能选择最佳方法

• batch：使用 Gitea 的批量 API 在单次提交中执行所有操作

• individual：将每个操作作为单独的提交执行

使用场景：

• 更新现有项目文件

• 选择性文件修改

• 批量文件操作（创建、更新、删除）

• 增量项目更新

• 自动化文件维护

示例：

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

工具选择指南

何时使用每个工具：

1. create_repository：创建新仓库

2. sync_project：将初始项目上传到空/新仓库

3. upload_files：上传特定文件并完全控制该过程

4. sync_update：更新现有文件、创建新文件或删除现有仓库中的文件

工作流示例：

# 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 - 构建生产版本

• npm run dev - 带有热重载的开发环境

• npm start - 启动生产服务器

• npm test - 运行测试

• npm run lint - 代码 Lint

• npm run format - 代码格式化

• npm run type-check - TypeScript 类型检查

项目结构

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

添加新工具

1. 在 src/tools/ 中创建工具实现

2. 在 src/tools/schemas.ts 中添加模式验证

3. 在 src/tools/index.ts 中注册工具

4. 在 tests/unit/tools/ 中添加测试

部署

Docker

使用 Docker 构建并运行：

# Build image
docker build -t gitea-mcp .

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

生产注意事项

• 使用环境变量或密钥管理来存储令牌

• 配置适当的日志级别

• 设置监控和健康检查

• 使用 PM2 等进程管理器来管理 Node.js 应用程序

• 考虑使用 Docker 或 Kubernetes 进行编排

安全

最佳实践

• 使用环境变量或密钥管理安全地存储令牌

• 为访问令牌使用最小必要权限

• 验证所有输入参数

• 记录安全事件而不暴露敏感数据

• 对所有 Gitea API 通信使用 HTTPS

• 定期轮换访问令牌

速率限制

服务器针对每个 Gitea 实例实施速率限制，以遵守 API 限制：

• 默认：每个实例每分钟 100 个请求

• 可通过实例配置中的 rateLimit 进行配置

• 具有指数退避的自动重试

故障排除

常见问题

身份验证失败

• 验证访问令牌是否正确且具有所需权限

• 检查令牌是否已过期

• 确保基础 URL 正确

速率受限

• 减少文件上传的批处理大小

• 调整速率限制配置

• 在重试请求前等待

文件上传失败

• 检查文件内容是否有效

• 验证文件路径不包含非法字符

• 确保仓库存在且您拥有写入权限

日志记录

启用调试日志以进行故障排除：

LOG_LEVEL=debug npm start

健康检查

检查服务器状态：

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

贡献

1. Fork 仓库

2. 创建功能分支

3. 进行更改并编写测试

4. 运行 Lint 和类型检查

5. 提交 Pull Request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

• GitHub Issues：报告错误和功能请求

• 文档：查看 docs/ 目录

• 示例：查看 examples/ 目录

为 Gitea 和 MCP 社区倾心打造。

另请参阅

• TranscriptionTools-MCP — 转录处理

• DeepLucid3D-MCP — 认知处理

• UNO-MCP — 叙事增强

• gitea-mcp — Gitea 集成

• zero-vector-MCP — 程序化生成