mcp-mokogitea-api/docs/API.md

API Reference

Full parameter reference for all 61 tools in gitea-api-mcp.

All tools accept an optional connection parameter (string) to select a named connection from your config. If omitted, the default connection is used.

Table of Contents

• User / Auth
• Repositories
• File Contents
• Branches
• Commits
• Issues
• Labels
• Milestones
• Pull Requests
• Releases
• Tags
• Actions
• Organizations
• Users
• Webhooks
• Wiki
• Notifications
• Generic

---

User / Auth

gitea_me

Get the authenticated user info.

Parameter	Type	Required	Description
connection	string	No	Named connection from config

gitea_user_orgs

List organizations the authenticated user belongs to.

Parameter	Type	Required	Description
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_user_repos

List repositories owned by the authenticated user.

Parameter	Type	Required	Description
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

---

Repositories

gitea_repo_get

Get repository details.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
connection	string	No	Named connection from config

gitea_repo_create

Create a new repository.

Parameter	Type	Required	Description
name	string	Yes	Repository name
org	string	No	Organization (omit for personal)
description	string	No	Description
private	boolean	No	Private repository
auto_init	boolean	No	Initialize with README
default_branch	string	No	Default branch (default "main")
template	boolean	No	Mark as template repository
connection	string	No	Named connection from config

gitea_repo_delete

Delete a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
connection	string	No	Named connection from config

gitea_repo_edit

Edit repository settings.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
description	string	No	New description
private	boolean	No	Set private/public
has_issues	boolean	No	Enable issues
has_wiki	boolean	No	Enable wiki
has_pull_requests	boolean	No	Enable PRs
default_branch	string	No	Default branch
archived	boolean	No	Archive/unarchive
connection	string	No	Named connection from config

gitea_repo_fork

Fork a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
organization	string	No	Fork to this org (omit for personal)
name	string	No	Custom name for fork
connection	string	No	Named connection from config

gitea_repo_search

Search repositories.

Parameter	Type	Required	Description
q	string	Yes	Search query
topic	boolean	No	Search in topics
sort	string	No	Sort field: alpha, created, updated, size, stars, forks
order	string	No	Sort order: asc, desc
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_org_repos

List repositories in an organization.

Parameter	Type	Required	Description
org	string	Yes	Organization name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_list_connections

List configured Gitea connections.

Parameter	Type	Required	Description
(none)

---

File Contents

gitea_file_get

Get file contents from a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
filepath	string	Yes	File path (e.g. "src/index.ts")
ref	string	No	Branch/tag/commit (default: default branch)
connection	string	No	Named connection from config

gitea_dir_get

Get directory contents (file listing) from a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
dirpath	string	No	Directory path (default: root)
ref	string	No	Branch/tag/commit
connection	string	No	Named connection from config

gitea_file_create_or_update

Create or update a file in a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
filepath	string	Yes	File path
content	string	Yes	File content (will be base64-encoded automatically)
message	string	Yes	Commit message
branch	string	No	Branch (default: default branch)
sha	string	No	SHA of existing file (required for updates)
connection	string	No	Named connection from config

gitea_file_delete

Delete a file from a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
filepath	string	Yes	File path to delete
sha	string	Yes	SHA of file to delete
message	string	Yes	Commit message
branch	string	No	Branch
connection	string	No	Named connection from config

gitea_tree_get

Get the git tree for a repository (recursive file listing).

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
sha	string	Yes	Tree SHA or branch name
recursive	boolean	No	Recursive listing (default true)
connection	string	No	Named connection from config

---

Branches

gitea_branches_list

List branches in a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_branch_get

Get a specific branch.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
branch	string	Yes	Branch name
connection	string	No	Named connection from config

gitea_branch_create

Create a new branch.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
new_branch_name	string	Yes	Name for new branch
old_branch_name	string	No	Source branch (default: default branch)
connection	string	No	Named connection from config

gitea_branch_delete

Delete a branch.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
branch	string	Yes	Branch name
connection	string	No	Named connection from config

---

Commits

gitea_commits_list

List commits in a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
sha	string	No	Branch or commit SHA
path	string	No	Filter by file path
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_commit_get

Get a specific commit.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
sha	string	Yes	Commit SHA
connection	string	No	Named connection from config

---

Issues

gitea_issues_list

List issues in a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
state	string	No	Issue state filter: open, closed, all
type	string	No	Filter by type: issues, pulls
labels	string	No	Comma-separated label names
milestones	string	No	Comma-separated milestone names
q	string	No	Search query
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_issue_get

Get a single issue by number.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	Issue number
connection	string	No	Named connection from config

gitea_issue_create

Create a new issue.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
title	string	Yes	Issue title
body	string	No	Issue body (markdown)
labels	number[]	No	Label IDs
milestone	number	No	Milestone ID
assignees	string[]	No	Usernames to assign
connection	string	No	Named connection from config

gitea_issue_update

Update an issue.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	Issue number
title	string	No	New title
body	string	No	New body
state	string	No	State: open, closed
assignees	string[]	No	Assignees
milestone	number	No	Milestone ID
connection	string	No	Named connection from config

gitea_issue_comments_list

List comments on an issue.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	Issue number
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_issue_comment_create

Add a comment to an issue.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	Issue number
body	string	Yes	Comment body (markdown)
connection	string	No	Named connection from config

gitea_issue_search

Search issues across all repositories.

Parameter	Type	Required	Description
q	string	Yes	Search query
state	string	No	State filter: open, closed, all
labels	string	No	Comma-separated label IDs
type	string	No	Filter type: issues, pulls
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

---

Labels

gitea_labels_list

List labels in a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_label_create

Create a label.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
name	string	Yes	Label name
color	string	Yes	Color hex (e.g. "#d73a4a")
description	string	No	Label description
connection	string	No	Named connection from config

---

Milestones

gitea_milestones_list

List milestones in a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
state	string	No	State filter: open, closed, all
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_milestone_create

Create a milestone.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
title	string	Yes	Milestone title
description	string	No	Description
due_on	string	No	Due date (ISO 8601)
connection	string	No	Named connection from config

---

Pull Requests

gitea_pulls_list

List pull requests.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
state	string	No	State filter: open, closed, all
sort	string	No	Sort: oldest, recentupdate, leastupdate, mostcomment, leastcomment, priority
labels	string	No	Comma-separated label IDs
milestone	number	No	Milestone ID
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_pull_get

Get a single pull request.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	PR number
connection	string	No	Named connection from config

gitea_pull_create

Create a pull request.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
title	string	Yes	PR title
head	string	Yes	Source branch
base	string	Yes	Target branch
body	string	No	PR description (markdown)
labels	number[]	No	Label IDs
milestone	number	No	Milestone ID
assignees	string[]	No	Assignees
connection	string	No	Named connection from config

gitea_pull_merge

Merge a pull request.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	PR number
merge_type	string	No	Merge method: merge, rebase, squash, rebase-merge (default: merge)
title	string	No	Custom merge commit title
message	string	No	Custom merge commit message
delete_branch_after_merge	boolean	No	Delete head branch after merge
connection	string	No	Named connection from config

gitea_pull_files

List files changed in a pull request.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	PR number
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_pull_review_create

Create a pull request review.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
number	number	Yes	PR number
event	string	Yes	Review action: APPROVED, REQUEST_CHANGES, COMMENT
body	string	No	Review comment
connection	string	No	Named connection from config

---

Releases

gitea_releases_list

List releases.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_release_get

Get a single release by ID.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
id	number	Yes	Release ID
connection	string	No	Named connection from config

gitea_release_latest

Get the latest release.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
connection	string	No	Named connection from config

gitea_release_create

Create a new release.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
tag_name	string	Yes	Tag name (e.g. "v1.0.0")
name	string	No	Release title
body	string	No	Release notes (markdown)
target_commitish	string	No	Target branch/commit
draft	boolean	No	Create as draft
prerelease	boolean	No	Mark as prerelease
connection	string	No	Named connection from config

gitea_release_delete

Delete a release.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
id	number	Yes	Release ID
connection	string	No	Named connection from config

---

Tags

gitea_tags_list

List tags.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_tag_create

Create a tag.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
tag_name	string	Yes	Tag name
target	string	No	Target branch/commit SHA
message	string	No	Tag message (annotated tag)
connection	string	No	Named connection from config

gitea_tag_delete

Delete a tag.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
tag	string	Yes	Tag name
connection	string	No	Named connection from config

---

Actions

gitea_actions_runs_list

List workflow runs for a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_actions_run_get

Get a specific workflow run.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
run_id	number	Yes	Run ID
connection	string	No	Named connection from config

---

Organizations

gitea_org_get

Get organization details.

Parameter	Type	Required	Description
org	string	Yes	Organization name
connection	string	No	Named connection from config

gitea_org_teams_list

List teams in an organization.

Parameter	Type	Required	Description
org	string	Yes	Organization name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_org_members_list

List members of an organization.

Parameter	Type	Required	Description
org	string	Yes	Organization name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

---

Users

gitea_user_get

Get a user profile.

Parameter	Type	Required	Description
username	string	Yes	Username
connection	string	No	Named connection from config

gitea_users_search

Search users.

Parameter	Type	Required	Description
q	string	Yes	Search query
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

---

Webhooks

gitea_webhooks_list

List webhooks for a repository.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_webhook_create

Create a webhook.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
type	string	Yes	Hook type: gitea, slack, discord, dingtalk, telegram, msteams, feishu, matrix, wechatwork, packagist
url	string	Yes	Webhook URL
events	string[]	No	Events to listen for (e.g. ["push", "pull_request"])
active	boolean	No	Active status
connection	string	No	Named connection from config

---

Wiki

gitea_wiki_pages_list

List wiki pages.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_wiki_page_get

Get a wiki page.

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (user or org)
repo	string	Yes	Repository name
page_name	string	Yes	Page name/slug
connection	string	No	Named connection from config

---

Notifications

gitea_notifications_list

List notifications for the authenticated user.

Parameter	Type	Required	Description
status_types	string	No	Comma-separated: read, unread, pinned
page	number	No	Page number (1-based)
limit	number	No	Items per page (max 50)
connection	string	No	Named connection from config

gitea_notifications_read

Mark all notifications as read.

Parameter	Type	Required	Description
connection	string	No	Named connection from config

---

Generic

gitea_api_request

Make a raw API request to any Gitea v1 endpoint.

Parameter	Type	Required	Description
method	string	Yes	HTTP method: GET, POST, PUT, PATCH, DELETE
endpoint	string	Yes	API endpoint path (e.g. "/repos/owner/repo")
body	object	No	Request body
params	object	No	Query parameters
connection	string	No	Named connection from config

gitea_list_connections

List configured Gitea connections.

Parameter	Type	Required	Description
(none)