本文从 Obsidian 撰写发布

VS Code 通过 MCP 连接自托管 Gitea 完整教程

最后更新：2026-06-21
适用环境：Windows 10/11 + Docker Desktop + VS Code + Cline
Gitea 版本：1.25.4

📌 概述

本教程记录如何通过 VS Code 的 MCP（Model Context Protocol）功能，连接自托管的 Gitea 服务器，并使用自然语言管理 Git 仓库。

实现效果

在 VS Code 中用中文对话管理 Gitea 仓库
无需打开浏览器即可创建、查看、管理仓库
支持列出仓库、创建仓库、管理 Issue、查看文件等操作

🏗️ 整体架构

┌─────────────────────────────────────────────────────────────┐
│                      你的本地电脑                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    VS Code                          │   │
│  │  ┌─────────────┐    ┌──────────────────────────┐  │   │
│  │  │   Cline     │ ←→ │   gitea-mcp (MCP Server) │  │   │
│  │  │ (AI助手)    │    │   (运行在 Docker 容器)    │  │   │
│  │  └─────────────┘    └────────────┬─────────────┘  │   │
│  └───────────────────────────────────┼────────────────┘   │
│                                      │                      │
│  ┌───────────────────────────────────▼────────────────┐   │
│  │              Docker Desktop (本地)                │   │
│  └────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    远程服务器                           │
│  ┌──────────────────────────────────────────────────┐  │
│  │         Gitea 容器 (自托管)                      │  │
│  │         https://gi.你的域名.com                  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

📋 前置要求

Windows 10/11 系统（本教程以 Windows 为例）
自托管的 Gitea 服务器（已运行并可通过域名访问）
稳定的网络连接

第一步：安装 Docker Desktop

1.1 下载安装包

访问 Docker 官网下载 Docker Desktop for Windows。

1.2 安装选项

安装时选择 "All Users"（为所有用户安装）
勾选 "Use WSL 2 instead of Hyper-V" 选项

说明：选择 "All Users" 可以避免后续权限问题。WSL 2 比 Hyper-V 性能更好、资源占用更少。

1.3 配置 WSL 2 环境

以管理员身份打开 PowerShell，依次运行：

# 1. 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. 重启电脑（必须！）

重启后，继续：

# 4. 更新 WSL 内核
wsl --update

# 5. 将 WSL 2 设为默认版本
wsl --set-default-version 2

# 6. 验证 WSL 版本
wsl --version

验证成功示例：

WSL 版本： 2.7.8.0
内核版本： 6.18.33.1-1
WSLg 版本： 1.0.73.2

1.4 验证 Docker 安装

启动 Docker Desktop，等待鲸鱼图标变为彩色静止状态。

在命令提示符中验证：

docker --version

成功示例：

Docker version 29.5.3, build d1c06ef

第二步：获取 Gitea 个人访问令牌

登录你的 Gitea 网站（例如 https://gi.你的域名.com）
点击右上角头像 → 设置
左侧菜单 → 应用
在"管理个人访问令牌"区域：
- 输入令牌名称（如 vscode-mcp）
- 必须勾选 repo 权限范围（MCP 需要读写仓库）
- 点击 生成令牌
立即复制并保存令牌（关闭页面后无法再次查看）

重要：令牌权限至少需要 repo 范围。不要选择"仅公开"，否则 MCP 无法执行创建、修改等写入操作。

第三步：配置 VS Code MCP

3.1 确认 VS Code 版本

VS Code 需要 1.95.0 或更高版本 才支持 MCP 功能。

检查版本：帮助 → 关于

3.2 配置 mcp.json

在 mcp.json（用户级别或项目级别）中添加配置：

{
    "servers": {
        "gitea-mcp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "GITEA_ACCESS_TOKEN",
                "-e",
                "GITEA_HOST",
                "docker.gitea.com/gitea-mcp-server"
            ],
            "env": {
                "GITEA_ACCESS_TOKEN": "你的令牌",
                "GITEA_HOST": "https://你的Gitea地址"
            },
            "type": "stdio"
        }
    }
}

⚠️ 常见错误：

错误配置	正确配置
`"GITEA_HOST": "http://localhost:8084"`	`"GITEA_HOST": "https://你的Gitea域名"`
`"GITEA_HOST": "https://域名/api/v1"`	不需要加 `/api/v1`，MCP 会自动拼接
使用 `"${input:gitea_token}"` 但 inputs 未配置	直接硬编码令牌，或正确配置 inputs

3.3 验证 MCP 是否启动

在 VS Code 中按 Ctrl+Shift+P，输入 MCP: Show Servers。

成功状态应显示：

gitea-mcp ✅ Connected

3.4 手动测试 MCP 服务器

在命令提示符中运行以下命令，验证 MCP 能否获取仓库列表：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_my_repos","arguments":{}}}' | docker run -i --rm -e GITEA_HOST="https://你的Gitea地址" -e GITEA_ACCESS_TOKEN="你的令牌" docker.gitea.com/gitea-mcp-server

成功时返回 JSON 格式的仓库列表数据。

第四步：配置 Cline + DeepSeek

4.1 安装 Cline 扩展

在 VS Code 扩展商店搜索 Cline 并安装。

4.2 获取 DeepSeek API Key

访问 DeepSeek 开放平台
使用国内手机号注册账号
进入控制台 → API Keys → 创建 API Key
复制保存 API Key（格式：sk-xxxxxxxxxxxxx）

4.3 在 Cline 中配置 DeepSeek

点击 VS Code 左侧 Cline 图标
点击右上角 齿轮图标（设置）
配置如下：

配置项	填写内容
API Provider	`OpenAI Compatible`
API Key	你的 DeepSeek API Key
Base URL	`https://api.deepseek.com/v1`
Model	`deepseek-chat`

4.4 配置 Cline 的 MCP

在 cline_mcp_settings.json 中配置：

文件路径：

C:\Users\你的用户名\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

配置内容：

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITEA_ACCESS_TOKEN",
        "-e",
        "GITEA_HOST",
        "docker.gitea.com/gitea-mcp-server"
      ],
      "env": {
        "GITEA_ACCESS_TOKEN": "你的令牌",
        "GITEA_HOST": "https://你的Gitea地址"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

注意：如果 VS Code 的 MCP 配置已生效，Cline 可以自动识别。否则需要在 cline_mcp_settings.json 中独立配置。

第五步：测试使用

5.1 基础命令

在 Cline 聊天框中输入：

列出我的所有仓库

成功后应显示仓库列表，格式类似：

📦 Typecho 插件（21个）
1. ArticleWeather - 文章发布地点、天气插件
2. AutoTagLink - 文章标签分类自动内链插件
...

5.2 常用操作命令

操作	命令示例
列出仓库	`列出我的所有仓库`
查看用户	`获取我的用户信息`
创建仓库	`创建一个名为 test-project 的公开仓库`
搜索仓库	`搜索名字里带有 "Plugin" 的仓库`
查看 Issue	`列出 XIGE/仓库名的所有 Issue`
创建 Issue	`在 XIGE/仓库名中创建 Issue，标题是 "xxx"`
获取文件	`获取 XIGE/仓库名中 README.md 的内容`

🐛 常见问题与解决方案

问题 1：`spawn docker ENOENT`

现象：VS Code 启动 MCP 时报错 spawn docker ENOENT

原因：系统 PATH 中找不到 docker 命令

解决方案：

方案 A - 使用 Docker 完整路径：

"command": "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe"

方案 B - 从终端启动 VS Code：

code

方案 C - 重启电脑（刷新环境变量）

问题 2：Cline 找不到 MCP 服务器

现象：Cline 提示 No connection found for server: gitea-mcp

原因：Cline 的 MCP 配置未生效

解决方案：

确认 cline_mcp_settings.json 文件在正确路径

文件路径必须包含 settings 文件夹：

...\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

重启 VS Code

问题 3：Shell 集成不可用

现象：Cline 提示 Shell Integration Unavailable，无法显示命令输出

原因：VS Code 终端 Shell 集成配置问题

解决方案：

以管理员身份打开 PowerShell
检查执行策略：
```
Get-ExecutionPolicy
```

如果为 Restricted，修改为：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

重启 VS Code

问题 4：令牌权限不足

现象：MCP 返回 401 或权限错误

原因：生成的令牌未勾选 repo 范围

解决方案：重新生成令牌，确保勾选 repo 权限

问题 5：Gitea 地址配置错误

现象：MCP 无法连接 Gitea 服务器

错误配置：

"GITEA_HOST": "http://localhost:8084"

正确配置（Gitea 在远程服务器）：

"GITEA_HOST": "https://你的域名.com"

✅ 成功标志

配置成功后，你可以：

MCP: Show Servers 显示 gitea-mcp ✅ Connected
docker --version 正常显示版本
在 Cline 中输入 列出我的所有仓库 返回仓库列表
可以在 VS Code 中用自然语言管理 Gitea

📊 最终配置清单

组件	状态	备注
Docker Desktop	✅ 运行中	版本 29.5.3
WSL 2	✅ 已启用	版本 2.7.8.0
Gitea 服务器	✅ 运行中	版本 1.25.4
VS Code MCP	✅ 已配置	gitea-mcp Connected
Cline	✅ 已配置	DeepSeek API
Gitea Token	✅ 有效	有 `repo` 权限

📚 参考资源

📝 备注

本教程中所有域名、令牌均为演示用途，请替换为实际值
配置完成后建议保存一份备份配置文件
如果需要在其他电脑上复现，按本教程步骤操作即可

# vs code # gitea

VS Code 通过 MCP 连接自托管 Gitea 完整教程

📌 概述

实现效果

🏗️ 整体架构

📋 前置要求

第一步：安装 Docker Desktop

1.1 下载安装包

1.2 安装选项

1.3 配置 WSL 2 环境

1.4 验证 Docker 安装

第二步：获取 Gitea 个人访问令牌

第三步：配置 VS Code MCP

3.1 确认 VS Code 版本

3.2 配置 mcp.json

3.3 验证 MCP 是否启动

3.4 手动测试 MCP 服务器

第四步：配置 Cline + DeepSeek

4.1 安装 Cline 扩展

4.2 获取 DeepSeek API Key

4.3 在 Cline 中配置 DeepSeek

4.4 配置 Cline 的 MCP

第五步：测试使用

5.1 基础命令

5.2 常用操作命令

🐛 常见问题与解决方案

问题 1：spawn docker ENOENT

问题 2：Cline 找不到 MCP 服务器

问题 3：Shell 集成不可用

问题 4：令牌权限不足

问题 5：Gitea 地址配置错误

✅ 成功标志

📊 最终配置清单

📚 参考资源

📝 备注

问题 1：`spawn docker ENOENT`