gitea-mcp/README.zh-tw.md

Gitea MCP 伺服器

English | 简体中文

Gitea MCP 伺服器 將 Gitea 實例接入 Model Context Protocol 客戶端，讓倉庫、問題、拉取請求等都能在相容 MCP 的聊天介面中瀏覽與管理。

安裝

可從 發布頁面 下載二進位檔並放入 PATH，或使用 docker.gitea.com/gitea-mcp-server 映像檔，也可用 make 與 Go 1.26 以上從原始碼建置到 $GOPATH/bin：

git clone https://gitea.com/gitea/gitea-mcp.git
cd gitea-mcp
make install

設定

Gitea 主機與存取令牌可透過命令列參數或環境變數提供，命令列參數優先。執行 gitea-mcp --help 可查看完整的參數與環境變數列表。日誌寫入 $HOME/.gitea-mcp/gitea-mcp.log，加上 -d 可啟用除錯日誌。

Claude Code

透過 go run 執行伺服器，需要安裝 Go：

claude mcp add --transport stdio --scope user gitea \
  --env GITEA_ACCESS_TOKEN=token \
  --env GITEA_HOST=https://gitea.com \
  -- go run gitea.com/gitea/gitea-mcp@latest -t stdio

VS Code

可使用本 README 頂部的安裝按鈕，或將下面的內容加入使用者設定 (JSON)，按 Ctrl + Shift + P 並輸入 Preferences: Open User Settings (JSON) 即可開啟。也可放在工作區的 .vscode/mcp.json 中，此時不需要 mcp 鍵。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "gitea_token",
        "description": "Gitea 個人存取令牌",
        "password": true
      }
    ],
    "servers": {
      "gitea-mcp": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
        "env": {
          "GITEA_ACCESS_TOKEN": "${input:gitea_token}"
        }
      }
    }
  }
}

OpenCode

將下面的內容加入 OpenCode 設定的頂層 mcp 物件：

    "gitea-mcp": {
      "enabled": true,
      "type": "local",
      "command": [
        "gitea-mcp",
        "-t", "stdio",
        "-H", "https://gitea.com",
        "-T", "<your personal access token>"
      ]
    }

Mistral Vibe

將下面的內容加入 ~/.vibe/config.toml：

[[mcp_servers]]
name = "gitea"
transport = "stdio"
command = "docker"
args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"]

[mcp_servers.env]
GITEA_ACCESS_TOKEN = "TOKEN"
GITEA_HOST = "https://gitea.com"

其他客戶端

Cursor 等客戶端可使用 stdio 命令：

{
  "mcpServers": {
    "gitea": {
      "command": "gitea-mcp",
      "args": ["-t", "stdio", "--host", "https://gitea.com"],
      "env": {
        "GITEA_ACCESS_TOKEN": "<your personal access token>"
      }
    }
  }
}

或使用 http 端點，對應以 gitea-mcp -t http --port 8080 啟動的伺服器：

{
  "mcpServers": {
    "gitea": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your personal access token>"
      }
    }
  }
}

設定完成後，可在聊天框輸入 列出我所有的倉庫 試試。

可用工具

工具	範圍	存取	描述
get_gitea_mcp_server_version	version	讀取	取得 Gitea MCP 伺服器版本
get_me	user	讀取	取得目前已認證用戶
get_user_orgs	user	讀取	列出目前用戶的組織
search_users	search	讀取	搜尋用戶
search_org_teams	search	讀取	搜尋組織中的團隊
search_repos	search	讀取	搜尋倉庫
search_issues	search	讀取	跨倉庫搜尋問題和拉取請求
notification_read	notification	讀取	讀取通知：列出（可限定倉庫）或依 ID 取得會話
notification_write	notification	寫入	將某條或全部通知標記為已讀
label_read	label	讀取	讀取倉庫或組織標籤
label_write	label	寫入	寫入標籤（倉庫或組織）：創建、編輯、刪除
milestone_read	milestone	讀取	讀取里程碑：取得單個或列出
milestone_write	milestone	寫入	寫入里程碑：創建、更新、刪除
wiki_read	wiki	讀取	讀取 Wiki：列出頁面、取得內容、修訂歷史
wiki_write	wiki	寫入	寫入 Wiki 頁面：創建、更新、刪除
timetracking_read	timetracking	讀取	讀取時間追蹤：問題/倉庫耗時、活動計時器、我的追蹤記錄
timetracking_write	timetracking	寫入	寫入時間追蹤：計時器和記錄項目
package_read	packages	讀取	讀取軟體套件註冊表：列出套件、列出版本或取得某個版本
package_write	packages	寫入	刪除軟體套件版本（不可復原）
list_issues	issue	讀取	列出倉庫問題
attachment_read	issue	讀取	讀取問題/評論附件：列出中繼資料、取得中繼資料或下載內容
issue_read	issue	讀取	讀取問題：詳情、評論或標籤
issue_write	issue	寫入	寫入問題：創建、更新、管理評論和標籤
list_pull_requests	pull_request	讀取	列出倉庫拉取請求
pull_request_read	pull_request	讀取	讀取拉取請求：詳情、差異、變更檔案、頭部提交狀態、審查
pull_request_write	pull_request	寫入	寫入拉取請求：創建、更新、關閉、重新開啟、合併、更新分支、管理審查者
pull_request_review_write	pull_request	寫入	寫入 PR 審查：創建、提交、刪除、駁回
actions_config_read	actions	讀取	讀取 Actions 密鑰和變數
actions_config_write	actions	寫入	寫入 Actions 密鑰和變數：更新插入、創建、更新、刪除
actions_run_read	actions	讀取	讀取 Actions 工作流程、執行、作業、日誌和產物
actions_run_write	actions	寫入	寫入 Actions 執行：觸發、取消、重新執行
create_repo	repository	寫入	創建新倉庫
fork_repo	repository	寫入	復刻倉庫
list_my_repos	repository	讀取	列出目前用戶擁有的倉庫
list_org_repos	repository	讀取	列出組織中的倉庫
get_repository_tree	repository	讀取	取得倉庫檔案樹
get_file_contents	file	讀取	取得檔案內容與中繼資料
get_dir_contents	file	讀取	取得目錄中的項目
create_or_update_file	file	寫入	創建或更新檔案（提供 sha 以更新現有檔案）
delete_file	file	寫入	刪除檔案
create_branch	branch	寫入	創建新分支
delete_branch	branch	寫入	刪除分支
list_branches	branch	讀取	列出倉庫分支
create_tag	tag	寫入	創建標籤
delete_tag	tag	寫入	刪除標籤
get_tag	tag	讀取	取得標籤詳情
list_tags	tag	讀取	列出倉庫標籤
list_commits	commit	讀取	列出倉庫提交
get_commit	commit	讀取	取得提交詳情
create_release	release	寫入	創建版本發布
delete_release	release	寫入	刪除版本發布
get_release	release	讀取	依 ID 取得版本發布
get_latest_release	release	讀取	取得最新版本發布
list_releases	release	讀取	列出倉庫版本發布

說明： 部分工具是聚合的、基於操作的工具，單個工具透過 method 參數暴露多個操作。當伺服器以唯讀模式執行時（-r / GITEA_READONLY），存取為「寫入」的工具會被隱藏；可透過 -S / --scope（GITEA_SCOPES）依範圍過濾，或透過 -O / --tools（GITEA_TOOLS）依工具名稱過濾對外暴露的工具集合。

未設定任一參數時，會載入所有工具；僅設定 --scope 時，會載入這些範圍內的所有工具；僅設定 --tools 時，只會載入指定名稱的工具；兩者皆設定時，會載入所選範圍的工具與指定工具名稱的聯集。範圍名稱即上表「範圍」欄中的值，未知的範圍名稱僅會在啟動時發出警告並被忽略。

gitea-mcp -S issue,pull_request
gitea-mcp --scope repository,branch --tools get_me

許多工具支援 page 和 per_page 分頁參數。最大有效頁面大小由 Gitea 伺服器的 [api].MAX_RESPONSE_ITEMS 設定決定（預設 50），超出的值會被靜默截斷。