# 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](#user--auth) - [Repositories](#repositories) - [File Contents](#file-contents) - [Branches](#branches) - [Commits](#commits) - [Issues](#issues) - [Labels](#labels) - [Milestones](#milestones) - [Pull Requests](#pull-requests) - [Releases](#releases) - [Tags](#tags) - [Actions](#actions) - [Organizations](#organizations) - [Users](#users) - [Webhooks](#webhooks) - [Wiki](#wiki) - [Notifications](#notifications) - [Generic](#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)* | | | |