gitea-mcp

Make an issue block another issue. index is the blocker; dep_index becomes blocked by (dependent on) index. dep_owner/dep_repo default to the same repo but may point at another repo (requires AllowCrossRepositoryDependencies). Returns the blocker issue.

Make an issue depend on (be blocked by) another issue. index is the issue that gains the dependency; dep_index is the blocker. dep_owner/dep_repo default to the same repo but may point at another repo (requires the instance to enable AllowCrossRepositoryDependencies). Returns the target issue (the dependent one).

Add labels to an issue by its index. labels is an array of label NAMES (strings) — NOT ids. Get valid names from list_labels; a name that does not exist errors (404). ADDITIVE: existing labels are kept. Duplicate names (both within the input and against labels already on the issue) are filtered out automatically — only labels not yet present are added.

Add ONE topic to a repository by name. Idempotent: adding an existing topic does not error. Topic name: lowercase letters, digits, and hyphens, starting with a letter/digit. To add several topics at once or to set the exact desired set, prefer replace_topics.

Cancel one Actions workflow run by runId. Only valid on runs that are still ACTIVE (status: queued, waiting, in_progress, running, pending) — cancelling an already-completed run returns an error. PARTIALLY DESTRUCTIVE: active jobs are killed and their partial results are discarded. ALWAYS call get_action_run first to confirm the run is still active, and confirm the runId with the user before cancelling. The run's conclusion becomes 'cancelled' after a successful cancel.

Check whether an issue is blocked — i.e. has at least one dependency that is not yet closed (state !== "closed"). Returns a single structured verdict: blocked, blockers (the open dependency issues), total_dependencies, and open_blockers. A convenience aggregator over list_issue_dependencies that paginates internally (no page/limit input). Returns 404 if the repo has not enabled issue dependencies (enable_issue_dependencies).

Remove ALL labels from an issue by its index. Destructive for that issue's labels. Confirm with the user first; if a known subset must remain, use replace_issue_labels with that subset instead.

Configure the Gitea connection at runtime (session-scoped, never persisted). Accepts base_url, owner, repo, and/or username — at least one is required. Providing base_url or username triggers credential re-discovery from the existing four sources (GITEA_REPO_URL repo URL, git config [gitea] token, GITEA_TOKEN env, git credential helpers). Tokens never pass through this tool; they are always read from the local credential sources. username strictly narrows the git credential lookup to that identity (no fallback to other identities). Use this when the server started unconfigured or when you need to switch instances/identities mid-session.

Add a comment to an issue by its index. body is required and supports Markdown. Returns the comment including its id — retain it to later update_comment/delete_comment that exact comment.

Create an issue. title is required. labels takes label IDs (numbers) — call list_labels first to map names to IDs, or add labels by name after creation via add_issue_labels. assignees is an array of usernames. Returns the created issue including its number.

Upload a local file as an attachment on an issue by its index (multipart/form-data). file_path reads a LOCAL file from the machine running gitea-mcp — confirm with the user before uploading any file. The path is confined: it must resolve inside the server's working directory (or GITEA_UPLOAD_ROOT), pass a filename-extension allow-list, avoid sensitive locations (.git, .env*, keys), and stay under a 50 MiB cap. Optional name overrides the stored filename (defaults to the file's basename). Returns the created attachment including its id. RISK: instances can disable attachments (404) and cap upload size (oversized files fail 413/422).

Upload a local file as an attachment on one issue COMMENT by its comment_id (get the id from list_comments; multipart/form-data, same shape and rules as create_issue_attachment). file_path reads a LOCAL file from the machine running gitea-mcp — confirm with the user before uploading any file. The path is confined the same way (upload root, extension allow-list, sensitive locations, 50 MiB cap). Optional name overrides the stored filename (defaults to the file's basename). Returns the created attachment including its id. RISK: instances can disable attachments (404) and cap upload size (oversized files fail 413/422).

Create a label. name required and MUST be unique in the repo (a duplicate -> conflict error). color is 6-digit hex, with or without a leading '#' (e.g. '#ff0000' or 'ff0000'). description optional. Returns the label with its id.

Create a milestone. title required. description optional. due_on optional ISO 8601 (e.g. '2025-12-31T23:59:59Z'). New milestones start in state 'open'. Returns the milestone with its id.

Create a pull request. title, head (source branch), and base (target branch) are required. For cross-fork PRs use 'owner:branch' in head. labels takes label IDs (numbers) — call list_labels first. Prefix the title with WIP: or [WIP] to prevent accidental merge while work is in progress. Returns the created PR including its number.

Create a release. tag_name is required (the Git tag, e.g. 'v1.2.0'); the tag is created if it does not exist. name is the human-readable title; body is the release notes (Markdown). target_commitish (branch or SHA) controls where the tag points (defaults to the repo's default branch). draft and prerelease are optional booleans. Returns the created release including its numeric id.

Create a wiki page. title is required ('Home' is the wiki landing page; '_Sidebar' / '_Footer' are the layout pages). content is plain Markdown — base64 encoding is handled for you. message is an optional commit message. RISK: fails if a page with that title already exists — call list_wiki_pages or get_wiki_page first and use update_wiki_page for existing pages. Returns the created page with decoded content.

Delete a comment by its id (NOT the issue index — get the id from list_comments). IRREVERSIBLE. Confirm with the user first; only the author or a repo admin may delete (403 otherwise).

PERMANENTLY delete an issue by index. IRREVERSIBLE (no recycle bin) and may fail if the instance disallows deletion. Confirm the index with the user first; prefer update_issue({ state: 'closed' }) to close instead of delete.

Delete one issue attachment by attachment_id (get the id from list_issue_attachments). IRREVERSIBLE. Confirm the attachment id with the user first.

Permanently delete a label by id (number — NOT the name). IRREVERSIBLE and also removes it from EVERY issue that currently has it. Get the id from list_labels and confirm with the user before deleting.

Permanently delete a milestone by id. IRREVERSIBLE. Issues assigned to it are NOT deleted — they keep existing but lose the milestone assignment (milestone becomes null). Confirm with the user first; prefer update_milestone({ state: 'closed' }) to preserve history.

PERMANENTLY delete a release by its numeric id (NOT the tag name). IRREVERSIBLE. Depending on Gitea configuration the underlying Git tag may or may not be deleted too. Confirm the id with the user first; prefer update_release({ draft: true }) to unpublish without deleting.

PERMANENTLY delete a wiki page by pageName. The page is removed from the wiki; its history survives only in the wiki git repository (clone .wiki.git to recover), so treat this as IRREVERSIBLE from the API. Confirm the pageName with the user first; prefer update_wiki_page to blank or redirect a page instead of deleting it.

Edit one issue attachment by attachment_id — renames it (name is the new filename). Get the id from list_issue_attachments.

Fetch one Actions workflow run by its runId (the numeric run ID from list_action_runs or the Gitea web UI — NOT the workflow name or index). Returns the full run including status, conclusion, head_branch, head_sha, event, started_at, completed_at, and actor. Call this BEFORE cancel_action_run (to verify the run is still active) or rerun_action_run (to verify it has completed and is rerunnable).

Fetch one issue by its index — the number shown in the issue URL (e.g. #42), NOT the internal id. Use to read the full body, labels, assignee, or milestone of a single issue.

Fetch one issue attachment's metadata by attachment_id (get the id from list_issue_attachments). Returns id, name, size, download_count, browser_download_url — it does NOT download the file content.

Fetch one milestone by id (the internal id from list_milestones, NOT the title). Returns progress counts (open_issues / closed_issues), description, state, and due_on.

Fetch one repository project board (kanban) by id. PLACEHOLDER: always reports not-found (HTTP 404 semantics) because Gitea does not yet ship a REST API for project boards (go-gitea/gitea#36824). No HTTP request is made. The contract is stable so workflows can attempt to look up a project without breaking; the real endpoint will be wired transparently once the upstream API lands.

Fetch one pull request by its index — the number shown in the PR URL (e.g. #42), NOT the internal id. Returns the full PR including base/head branches, mergeable status, merged flag, labels, and milestone.

Fetch one release by its numeric id (NOT the tag name — get the id from list_releases). Returns the full release including the title (name), release notes (body), tag_name, draft/prerelease flags, target_commitish, and attachments. Use get_release_by_tag to look up a release when you only know the tag name.

Fetch one release by its tag name (e.g. 'v1.2.0'). Useful when you only know the Git tag, not the numeric release id. Returns the same release shape as get_release; the response includes the id needed for update_release/delete_release.

Fetch one wiki page by its pageName — the page title as it appears in the wiki URL (e.g. 'Home', 'Getting-Started'). Returns the full page with content DECODED to plain Markdown (the API's base64 is handled for you), plus footer, sidebar, commit_count, and last_commit. Use list_wiki_pages first if you are unsure of the exact page name.

Report the resolved connection and credential state: whether the server is configured, the current baseUrl, every discovered credential candidate (source, schemes, status, masked username, secretPresent boolean), whether the git binary could be used for credential discovery (gitAvailable — false means only GITEA_REPO_URL / GITEA_TOKEN env or anonymous mode remain: install git or set GITEA_REPO_URL / GITEA_TOKEN), and the session-scoped target (owner, repo, username). Secrets are NEVER returned. Use this when a tool returns 401/403 or NotConfiguredError to diagnose the connection state. Takes no input.

Check whether a pull request has been merged. Returns a boolean (true = merged, false = not merged). Call before merge_pull_request to avoid a redundant attempt, or to confirm a PR's final state.

List Gitea Actions workflow runs in one repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Filters: branch, event (push, pull_request, schedule, etc.), status (pending, queued, waiting, in_progress, running, success, failure, skipped, cancelled), actor (username that triggered the run), head_sha. The response is a wrapper object { workflow_runs: [...], count: number } — the runs live under the workflow_runs key, NOT at the top level. Use this to find a run's id before calling get_action_run, cancel_action_run, or rerun_action_run.

List comments on one issue by its index. RISK: returns only the server's DEFAULT first page (this tool exposes no pagination), so long threads may be TRUNCATED — do not assume a short list means few comments. Gitea returns oldest-first. Each comment has an id (used to update/delete it), body (Markdown), user, and timestamps.

List the attachments on one issue by its index. Each attachment has id (used by get/edit/delete_issue_attachment), name, size, download_count, and browser_download_url. RISK: instances can disable attachments (404 means the feature is off).

List the issues that are BLOCKED BY this issue (its 'blocking' dependents). Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Reverse direction of list_issue_dependencies (which lists the issues that block this one).

List the issues that BLOCK this issue (its 'blocked by' dependencies). Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Returns 404 if the repo has not enabled issue dependencies (enable_issue_dependencies). Use list_issue_blocks for the reverse direction (issues this issue blocks).

List issues in one Gitea repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Filters: state (default open), labels (comma-separated NAMES). RISK: Gitea may include pull requests here; to list only issues use search_issues with type='issues'. Example: list_issues({ state: 'open', page: 1, limit: 50 })

List labels in a repo. Paginated (page 1-based, limit <= 100); page until a page returns fewer than limit. Each label has id (number), name, color (hex), description. ALWAYS call this before any label mutation — label endpoints mix names and ids (add/replace use NAMES, remove/update/delete use IDS).

List milestones in a repo. Paginated (page 1-based, limit <= 100). RISK: Gitea's DEFAULT returns only OPEN milestones — pass state='all' or 'closed' if you need closed/completed ones. Each milestone has id, title, state, open_issues, closed_issues, due_on.

List repositories the authenticated token's user can access (across ALL owners/orgs). Paginated (page 1-based, limit <= 100). Each repo object is large — keep limit modest. Use to DISCOVER owner/repo values or find where to work, not to list one repo's issues.

List repository project boards (kanban). PLACEHOLDER: always returns an empty list because Gitea does not yet ship a REST API for project boards (go-gitea/gitea#36824). No HTTP request is made. The contract is stable so planning workflows can ask about projects without breaking; wiring the real endpoint will be a transparent change once the upstream API lands.

List the commits in one pull request by its index. Paginated (page 1-based, limit <= 100). Each entry has sha, html_url, the commit message, and an optional author. Useful for reviewing what a PR changes before merging.

List the files changed in one pull request by its index. Paginated (page 1-based, limit <= 100). Each entry has filename, status (added/modified/deleted/renamed), additions, deletions, changes, and html_url. Use to understand a PR's diff scope before reviewing or merging.

List pull requests in one Gitea repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Filters: state (default open), labels (comma-separated NAMES), sort, milestone. Example: list_pull_requests({ state: 'open', page: 1, limit: 50 }). Cross-repo PR search uses search_issues({ type: 'pulls' }).

List releases in one Gitea repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Optional filters: draft (true = drafts only, false = published only) and prerelease (true = prereleases only, false = stable only). Each release carries id (used by get_release/update_release/delete_release), tag_name, name (title), body (release notes), draft, prerelease, and attachments. Example: list_releases({ page: 1, limit: 50 })

List a repository's topics (tags). Returns the topic name list for the repo — useful to inspect classification before editing. Topic names are lowercase letters, digits, and hyphens. Paginated (page 1-based, limit <= 100).

List all wiki pages in one Gitea repository (metadata only: title, html_url, sub_url, last_commit — no page content). Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Requires the repo's wiki feature to be enabled (404 otherwise). Example: list_wiki_pages({ page: 1, limit: 50 })

List the revision history of one wiki page by pageName (newest first). Returns { commits: [{ sha, message, author, commiter }], count }. Paginated: page is 1-based; keep paging while a page returns a full page of commits. Use to audit who changed a page and when, before reverting or summarizing changes.

Merge a pull request by index. Do selects the strategy: 'merge' (merge commit), 'squash' (single commit), 'rebase' (rebase + fast-forward), 'rebase-merge' (rebase + merge commit). Optional MergeTitleField/MergeMessageField customize the merge commit; SHA guards against branch drift. IRREVERSIBLE — confirm the index, strategy, and that the PR is mergeable (get_pull_request mergeable: true) with the user BEFORE merging. Check is_pull_merged first if unsure.

Remove a block so index no longer blocks dep_index. dep_owner/dep_repo default to the same repo. Returns the blocker issue. 404 if dependencies are not enabled on the repo.

Remove a dependency so index is no longer blocked by dep_index. dep_owner/dep_repo default to the same repo. Returns the target issue (the formerly dependent one). 404 if dependencies are not enabled on the repo.

Remove ONE label from an issue. Takes the label id (number) — NOT the name. Get the id from list_labels (issue labels carry their id). Errors if the label is not currently on the issue.

Remove ONE topic from a repository by name. No error if the topic is not currently on the repo (idempotent delete). Topic name: lowercase letters, digits, and hyphens, starting with a letter/digit. Confirm with the user first.

REPLACE the issue's ENTIRE label set. labels is an array of label NAMES. Every existing label is removed and ONLY the listed ones remain. Read current labels first if any must survive; confirm with the user before replacing.

REPLACE a repository's ENTIRE topic set. topics is the full list of topic names that should remain after the call — every existing topic not listed is removed. Pass an empty array to clear all topics. Topic names: lowercase letters, digits, and hyphens, starting with a letter/digit. Read current topics with list_topics first if any must survive; confirm with the user before replacing.

Rerun an entire Actions workflow run by runId. Only valid on runs that have COMPLETED (status: success, failure, cancelled, skipped) — rerunning an active run returns an error. Requires Gitea 1.26.0+. Creates a NEW run (incrementing run_attempt); the original run is not modified. ALWAYS call get_action_run first to confirm the run has completed, and confirm the runId with the user before rerunning. To rerun ONLY the failed jobs instead of the whole run, use rerun_action_run_failed_jobs.

Rerun ONLY the failed jobs of an Actions workflow run by runId. More efficient than rerun_action_run when most jobs succeeded and only a subset failed. Only valid on completed runs. Requires Gitea 1.26.0+. ALWAYS call get_action_run first to confirm the run has completed and has failed jobs (conclusion: failure), and confirm the runId with the user before rerunning.

Detect baseUrl/owner/repo from a git repository's remotes (SSH or HTTPS). Reads upstream first, then origin, then any other remote; all discovered remotes are returned, with userinfo stripped from every echoed URL so a credentialed remote never leaks its secret. path defaults to the current directory. Call ONCE at the start of a session to establish owner/repo for later calls instead of guessing. Errors if no parseable remote is found.

Search issues (and pull requests) across ALL repositories the token can see, by keyword/type/state/labels. Use for 'find issues about X' or duplicate detection across repos; set type='issues' to exclude pull requests. For listing one repo's issues use list_issues instead.

Edit a comment by its id (NOT the issue index — get the id from list_comments). body is the full replacement Markdown. Only the comment author or a repo admin may edit (403 otherwise).

Update one issue by index (PATCH: only provided fields change). RISK: passing labels REPLACES the entire label set (give the full desired ID list) — to change a single label use add_issue_labels/remove_issue_label instead. state is 'open' or 'closed'; set milestone by ID.

Update a label by id (number — NOT the name). Provide any of name/color/description (PATCH semantics). color is 6-digit hex. Get the id from list_labels.

Update a milestone by id (PATCH: only provided fields change). Provide any of title/description/due_on/state. state is 'open' or 'closed'. NOTE: closing a milestone does NOT close its open issues (they stay open, merely ungrouped) — close the issues separately if required.

Update one pull request by index (PATCH: only provided fields change). Set state to 'closed' to close a PR WITHOUT merging (reopens with 'open'). RISK: passing labels REPLACES the entire label set (give the full desired ID list); base retargets the PR and is rarely reversible. To change a single label use add_issue_labels/remove_issue_label (PR #N == Issue #N — label endpoints are shared).

Update one release by numeric id (PATCH: only provided fields change). Edit name (title), body (release notes), toggle draft/prerelease, retarget via target_commitish, or rename the tag via tag_name. tag_name renames the underlying Git tag — use with care. Publish a draft by setting draft=false. Get the id from list_releases or get_release_by_tag first.

Edit ONE repository's metadata (PATCH: only provided fields change). Provide any of name/description/website/private/default_branch. Use description to change the repo description (pass an empty string to clear it). NOTE: name RENAMES the repo and changes its URL — confirm with the user first. Returns the updated repository.

Edit an existing wiki page by pageName (PATCH: only provided fields change). content is plain Markdown (base64 handled for you); omit it to keep the current content. RISK: passing title RENAMES the page, which breaks existing links to the old name. Read the page with get_wiki_page first if it may have changed since your last read. Returns the updated page with decoded content.