mcp-mokogitea-api/README.md

gitea-api-mcp

MCP server for Gitea REST API v1 operations -- 61 tools for complete Gitea instance management from Claude Code and other MCP clients.

Table of Contents

• Background
• Install
• Configuration
• Usage
• Tools
• Contributing
• License
• Revision History

Background

gitea-api-mcp is a Model Context Protocol (MCP) server that exposes 61 tools for interacting with the Gitea REST API v1. It supports multiple named connections, allowing you to manage several Gitea instances from a single server. Authentication uses Gitea's native Authorization: token header format.

Install

Prerequisites

• Node.js >= 20.0.0
• A Gitea instance with API access
• A Gitea access token (Settings > Applications > Generate Token)

Build from Source

git clone https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp.git
cd gitea-api-mcp
npm install
npm run build

Configuration

Create ~/.gitea-api-mcp.json:

{
  "defaultConnection": "moko",
  "connections": {
    "moko": {
      "baseUrl": "https://git.mokoconsulting.tech",
      "token": "your-gitea-access-token",
      "insecure": false
    }
  }
}

Config Fields

Field	Type	Required	Description
baseUrl	string	Yes	Base URL of your Gitea instance
token	string	Yes	Gitea API access token
insecure	boolean	No	Skip TLS verification (self-signed certs)

Override the config path with the GITEA_API_MCP_CONFIG environment variable.

Multi-Connection Example

{
  "defaultConnection": "moko",
  "connections": {
    "moko": {
      "baseUrl": "https://git.mokoconsulting.tech",
      "token": "token-for-moko-gitea"
    },
    "github-mirror": {
      "baseUrl": "https://gitea.example.com",
      "token": "token-for-mirror"
    }
  }
}

Usage

Claude Code Registration

Add to your Claude Code MCP config (~/.claude/claude_desktop_config.json or project-level .mcp.json):

{
  "mcpServers": {
    "gitea-moko": {
      "command": "node",
      "args": ["/path/to/gitea-api-mcp/dist/index.js"]
    }
  }
}

Multi-Connection Usage in Claude Code

When using multiple connections, pass the connection parameter to any tool:

Use gitea_repo_get with connection "github-mirror" to get owner/repo details.

If connection is omitted, the defaultConnection is used.

Tools

User / Auth (3 tools)

Tool	Description
gitea_me	Get the authenticated user info
gitea_user_orgs	List organizations the authenticated user belongs to
gitea_user_repos	List repositories owned by the authenticated user

Repositories (8 tools)

Tool	Description
gitea_repo_get	Get repository details
gitea_repo_create	Create a new repository
gitea_repo_delete	Delete a repository
gitea_repo_edit	Edit repository settings
gitea_repo_fork	Fork a repository
gitea_repo_search	Search repositories
gitea_org_repos	List repositories in an organization
gitea_list_connections	List configured Gitea connections

File Contents (5 tools)

Tool	Description
gitea_file_get	Get file contents from a repository
gitea_dir_get	Get directory contents (file listing) from a repository
gitea_file_create_or_update	Create or update a file in a repository
gitea_file_delete	Delete a file from a repository
gitea_tree_get	Get the git tree for a repository (recursive file listing)

Branches (4 tools)

Tool	Description
gitea_branches_list	List branches in a repository
gitea_branch_get	Get a specific branch
gitea_branch_create	Create a new branch
gitea_branch_delete	Delete a branch

Commits (2 tools)

Tool	Description
gitea_commits_list	List commits in a repository
gitea_commit_get	Get a specific commit

Issues (7 tools)

Tool	Description
gitea_issues_list	List issues in a repository
gitea_issue_get	Get a single issue by number
gitea_issue_create	Create a new issue
gitea_issue_update	Update an issue
gitea_issue_comments_list	List comments on an issue
gitea_issue_comment_create	Add a comment to an issue
gitea_issue_search	Search issues across all repositories

Labels (2 tools)

Tool	Description
gitea_labels_list	List labels in a repository
gitea_label_create	Create a label

Milestones (2 tools)

Tool	Description
gitea_milestones_list	List milestones in a repository
gitea_milestone_create	Create a milestone

Pull Requests (6 tools)

Tool	Description
gitea_pulls_list	List pull requests
gitea_pull_get	Get a single pull request
gitea_pull_create	Create a pull request
gitea_pull_merge	Merge a pull request
gitea_pull_files	List files changed in a pull request
gitea_pull_review_create	Create a pull request review

Releases (5 tools)

Tool	Description
gitea_releases_list	List releases
gitea_release_get	Get a single release by ID
gitea_release_latest	Get the latest release
gitea_release_create	Create a new release
gitea_release_delete	Delete a release

Tags (3 tools)

Tool	Description
gitea_tags_list	List tags
gitea_tag_create	Create a tag
gitea_tag_delete	Delete a tag

Actions (2 tools)

Tool	Description
gitea_actions_runs_list	List workflow runs for a repository
gitea_actions_run_get	Get a specific workflow run

Organizations (3 tools)

Tool	Description
gitea_org_get	Get organization details
gitea_org_teams_list	List teams in an organization
gitea_org_members_list	List members of an organization

Users (2 tools)

Tool	Description
gitea_user_get	Get a user profile
gitea_users_search	Search users

Webhooks (2 tools)

Tool	Description
gitea_webhooks_list	List webhooks for a repository
gitea_webhook_create	Create a webhook

Wiki (2 tools)

Tool	Description
gitea_wiki_pages_list	List wiki pages
gitea_wiki_page_get	Get a wiki page

Notifications (2 tools)

Tool	Description
gitea_notifications_list	List notifications for the authenticated user
gitea_notifications_read	Mark all notifications as read

Generic (2 tools)

Tool	Description
gitea_api_request	Make a raw API request to any Gitea v1 endpoint
gitea_list_connections	List configured Gitea connections

Contributing

See CONTRIBUTING.md for development guidelines.

License

GPL-3.0-or-later -- Copyright (C) 2026 Moko Consulting

Revision History

Version	Date	Description
0.0.1	2026-05-07	Initial release with 61 tools