skills/gitea/references/mcp-tools.md

Gitea MCP Tool Inventory

Tools exposed by the gitea MCP server (registered in repo .mcp.json at https://git-mcp.farh.net/mcp). All tool names below are prefixed mcp__gitea__ when invoked.

Many tools are consolidated under a method discriminator (e.g. issue_write(method="create", …)). Where that's the case, the methods are listed in the third column.

Repositories

Tool	Purpose	Notes
list_my_repos	List repos accessible to the authenticated user	Paginated
list_org_repos	List repos for a given org	Required: org
search_repos	Search across the instance	Required: query. Filters: isPrivate, isArchived, keywordIsTopic, keywordInDescription, ownerID, sort, order
create_repo	Create a personal or org repo	Required: name. Optional: organization, private, auto_init, gitignores, license, readme, template, trust_model, default_branch, object_format_name (sha1/sha256), issue_labels, description
fork_repo	Fork a repo	Required: user (source owner), repo. Optional: organization, name
get_repository_tree	Recursive tree listing	Required: owner, repo, tree_sha. Optional: recursive, paging

Files

Tool	Purpose	Notes
get_file_contents	Get a file at a ref	Required: owner, repo, ref, path. Optional: withLines (numbered output)
get_dir_contents	List a directory at a ref	Required: owner, repo, ref, path
create_or_update_file	Write a file in a single commit	Required: owner, repo, path, content, message, branch_name. Provide sha to update an existing file; omit to create. Use new_branch_name to commit onto a new branch
delete_file	Remove a file	Required: owner, repo, path, message, branch_name, sha

Branches

Tool	Purpose	Notes
list_branches	List branches	Required: owner, repo
create_branch	Create a branch	Required: owner, repo, branch. Optional: old_branch (defaults to repo default)
delete_branch	Delete a branch	Required: owner, repo, branch

Commits / Tags

Tool	Purpose	Notes
list_commits	List commits	Required: owner, repo. Optional: sha (start ref), path (filter to commits touching this path)
get_commit	Get a commit	Required: owner, repo, sha
list_tags	List tags	Required: owner, repo
get_tag	Get a tag	Required: owner, repo, tag_name
create_tag	Create a tag	Required: owner, repo, tag_name. Optional: target, message
delete_tag	Delete a tag	Required: owner, repo, tag_name

Releases

Tool	Purpose	Notes
list_releases	List releases	Required: owner, repo. Optional: is_draft, is_pre_release
get_release	Get a release by ID	Required: owner, repo, id
get_latest_release	Latest non-draft release	Required: owner, repo
create_release	Create a release	Required: owner, repo, tag_name, target, title. Optional: body, is_draft, is_pre_release
delete_release	Delete a release	Required: owner, repo, id

No "edit release" or "upload asset" tool — fall back to tea releases edit / tea releases assets for those.

Issues

Tool	Purpose	Methods
list_issues	Standalone list	Filters: state, labels[], since, before
search_issues	Cross-repo search	Required: query. Filters: state, type (issues/pulls), labels, owner
issue_read	Read details	get, get_comments, get_labels
issue_write	Mutate	create, update, add_comment, edit_comment, add_labels, remove_label, replace_labels, clear_labels. labels are IDs (numeric). assignees are usernames

Pull requests

Tool	Purpose	Methods
list_pull_requests	List PRs	Filters: state, milestone, sort (oldest, recentupdate, leastupdate, mostcomment, leastcomment, priority)
pull_request_read	Read details	get, get_diff, get_files, get_status (head commit status), get_reviews, get_review, get_review_comments
pull_request_write	Mutate	create, update, close, reopen, merge, update_branch, add_reviewers, remove_reviewers. Merge styles: merge, rebase, rebase-merge, squash, fast-forward-only. Optional head_commit_id for conflict detection; merge_when_checks_succeed, force_merge, delete_branch for merge
pull_request_review_write	Reviews	create, submit, delete, dismiss. States for create: APPROVED, REQUEST_CHANGES, COMMENT, PENDING. Supports inline comments[] with path + new_line_num/old_line_num

Labels

Tool	Purpose	Methods
label_read	Read	list_repo_labels, get_repo_label, list_org_labels
label_write	Mutate	create_repo_label, edit_repo_label, delete_repo_label, create_org_label, edit_org_label, delete_org_label. Org labels accept exclusive; repo labels accept is_archived. color is hex #RRGGBB

Milestones

Tool	Purpose	Methods
milestone_read	Read	list, get
milestone_write	Mutate	create, update (alias edit), delete. State enum: open, closed. due_on is a date string

Wiki

Tool	Purpose	Methods
wiki_read	Read	list, get (needs pageName), get_revisions (needs pageName)
wiki_write	Mutate	create (needs title, content), update (needs pageName, content), delete (needs pageName). Optional message is the commit message

See ../../gitea-wiki/SKILL.md for end-to-end wiki examples.

Actions

Tool	Purpose	Methods
actions_config_read	Read secrets/variables	list_repo_secrets, list_org_secrets, list_repo_variables, get_repo_variable, list_org_variables, get_org_variable
actions_config_write	Mutate secrets/variables	upsert_repo_secret, delete_repo_secret, upsert_org_secret, delete_org_secret, create_repo_variable, update_repo_variable, delete_repo_variable, create_org_variable, update_org_variable, delete_org_variable. Secret value field is data; variable value is value
actions_run_read	Read workflows/runs/jobs/logs	list_workflows, get_workflow (workflow_id may be ID or filename), list_runs, get_run, list_jobs, list_run_jobs, get_job_log_preview, download_job_log (output_path required). Log methods accept max_bytes and tail_lines
actions_run_write	Trigger/control runs	dispatch_workflow (needs workflow_id, ref; optional inputs), cancel_run, rerun_run

Notifications

Tool	Purpose	Methods
notification_read	Read	list (optional owner/repo to scope; filters: status, subject_type, since, before), get (by thread id)
notification_write	Mark read	mark_read (by thread id), mark_all_read (optionally scoped to a repo)

Packages

Tool	Purpose	Methods
package_read	Read	list (one entry per version; filter via q/type), list_versions, get (needs version)
package_write	Mutate	delete (irreversible)

Package type: container, npm, maven, pypi, cargo, generic.

Time tracking

Tool	Purpose	Methods
timetracking_read	Read	list_issue_times, list_repo_times, get_my_stopwatches, get_my_times
timetracking_write	Mutate	start_stopwatch, stop_stopwatch, delete_stopwatch, add_time (time in seconds), delete_time

Users / Orgs / Teams

Tool	Purpose	Notes
get_me	Current user	No args
get_user_orgs	Orgs of the current user	Paginated
search_users	Search users	Required: query
search_org_teams	Search teams in an org	Required: org, query. Optional: includeDescription

Server

Tool	Purpose
get_gitea_mcp_server_version	Returns the running MCP server version. Useful for confirming connectivity.

Coverage gaps (use tea or REST API instead)

The MCP server does not currently expose:

• Webhook CRUD — use tea webhooks ….
• Admin user CRUD — use tea admin users ….
• Release asset upload/management — use tea releases assets ….
• SSH key CRUD — use tea ssh-keys ….
• Login / instance setup — tea logins ….
• Repo edit/delete — tea repos edit / tea repos delete --owner X --name Y --force.
• tea pulls checkout / tea clone workflows that need local git state.