Skip to main content
Glama

gitea-mcp

A Model Context Protocol server for Gitea — lets AI assistants (Claude, ChatGPT, Copilot, and anything else that speaks MCP) read, create, and manage issues, repositories, and releases on any Gitea instance you can reach.

Also works against Forgejo and Codeberg (API-compatible).

Why

Self-hosted Gitea is a popular GitHub alternative for solo developers, small teams, and privacy-conscious organizations. With this MCP server installed, your AI assistant can:

  • File audit findings or refactor notes as Gitea issues without you leaving the chat

  • Triage a repo's open issues in natural language

  • Cut a release at the end of a coding session

  • Comment on issues across multiple repos in one pass

Related MCP server: forgejo-mcp

Features

Resource

Tools

Issues

create_issue, list_issues, get_issue, update_issue, add_comment

Repos

list_repos, list_labels, list_milestones, list_branches

Pulls

list_pull_requests, get_pull_request, add_comment_on_pr, create_pr, merge_pr

Files

read_file, commit_changes, create_branch

Releases

list_releases, create_release

Meta

get_server_info, get_server_version

  • Bearer authentication via Personal Access Token (PAT)

  • Async HTTP via httpx and FastMCP

  • Works with self-hosted Gitea, Forgejo, and Codeberg

Quick Start

1. Install

pip install gitea-mcp

Or with uv:

uv pip install gitea-mcp

2. Generate a Personal Access Token

In your Gitea instance, go to Settings → Applications → Generate New Token and grant at least:

  • read:repository

  • write:issue

  • read:user

Add write:repository if you also want to create releases.

3. Configure your MCP client

Claude Desktop (interactive): run

gitea-mcp init

It prompts for the Gitea URL and Personal Access Token, verifies the connection, and writes (or merges into) the right claude_desktop_config.json for your OS. Restart Claude Desktop and you're done.

To check that the server can reach your Gitea instance at any time:

gitea-mcp doctor

doctor reads GITEA_URL and GITEA_TOKEN from the environment, runs a GET /api/v1/user, and reports the authenticated username plus the state of the MCP tool surface. Exit 0 = ready; exit 1 = connection/load failure; exit 2 = missing config.

Any MCP client (manual): add gitea-mcp to the client's MCP config. The recommended form uses uvx so the client launches the latest published wheel in an isolated env without needing gitea-mcp on its own PATH (this is what gitea-mcp init writes):

{
  "mcpServers": {
    "gitea": {
      "command": "uvx",
      "args": ["gitea-mcp"],
      "env": {
        "GITEA_URL": "https://your-gitea-instance.example.com",
        "GITEA_TOKEN": "your-personal-access-token"
      }
    }
  }
}

If you'd rather use a globally pip-installed gitea-mcp binary, drop args and set command to "gitea-mcp" directly — works as long as the binary is on the MCP client's PATH at launch time.

See mcp.json for a complete example. The same shape works for Claude Desktop, VS Code, Cowork, Claude Code, and any other MCP-compatible client.

Configuration

Configuration is read from environment variables.

Variable

Required

Default

Description

GITEA_URL

Yes

—

Base URL of your Gitea instance (e.g., https://gitea.example.com)

GITEA_TOKEN

Yes

—

Personal Access Token from your Gitea user settings

GITEA_TIMEOUT

No

30

HTTP request timeout in seconds

GITEA_MAX_RETRIES

No

3

Max retries for transient failures on idempotent methods (GET/PUT/DELETE). Set to 0 to disable retries. POST and PATCH are never auto-retried — they could create duplicate issues, comments, or releases. 429 Too Many Requests is retried for any method, honoring Retry-After when present.

GITEA_RETRY_BASE_DELAY

No

0.5

Base delay (seconds) for exponential backoff between retries. Effective delay grows as base * 2^attempt with jitter, capped at 4 seconds.

Self-hosting / HTTP transport

By default gitea-mcp runs in stdio mode — each MCP client (Claude Desktop, Cowork, etc.) launches its own subprocess on demand. For self-hosting one instance that multiple clients connect to over the network, use the streamable-HTTP transport:

gitea-mcp serve --transport http --host 0.0.0.0 --port 8000 --path /mcp

All four flags can also be provided via environment variables (handy for Docker / systemd units):

Variable

Default

Flag

GITEA_MCP_TRANSPORT

stdio

--transport

GITEA_MCP_HOST

127.0.0.1

--host

GITEA_MCP_PORT

8000

--port

GITEA_MCP_PATH

/mcp

--path

MCP clients connect to the resulting URL (e.g. https://gitea-mcp.example.com/mcp) just like they would to a local stdio server, except they share the one running instance.

Auth model (this release). The server reads GITEA_TOKEN from its own environment, so any client that reaches the URL acts as that one Gitea user. Run it for yourself behind your own access controls (firewall, reverse-proxy auth, VPN, Tailscale). Multi-tenant bring-your-own-token is on the roadmap.

The no-args invocation (gitea-mcp with no subcommand) still runs in stdio mode, so existing Claude Desktop / Cowork / Claude Code integrations are unaffected by this addition.

Compatibility

Server

Status

Gitea (self-hosted)

✅ Primary target

Forgejo

✅ Expected to work (API-compatible)

Codeberg

✅ Expected to work (Codeberg runs Forgejo)

Development

git clone https://github.com/werebear73/gitea-mcp.git
cd gitea-mcp
pip install -e ".[dev]"
pre-commit install                       # commit-stage hooks (ruff + mypy)
pre-commit install --hook-type pre-push  # push-stage hooks (pytest + build check)
pytest

The two-stage pre-commit policy keeps the commit loop snappy (lint + type only) while making git push block on the slow stuff that's actually caught CI/release bugs in the past — the full test suite and python -m build && twine check dist/*, which surfaces setuptools_scm version surprises before they reach a tag push.

Roadmap

See docs/ROADMAP.md for what's shipped, what's next, and what's out of scope.

Publishing

Versioning

Semantic versioning, derived from git tags via setuptools_scm. See VERSIONING.md for the release process.

Contributing

Issues and pull requests welcome. For substantial changes, please open an issue first to discuss the approach.

License

MIT — use it however you like, including commercial products.


Built by Waretech Services.

Available Tools

21 tools
add_commentB

Add a comment to an existing issue. Returns the created Comment object.

Inputs: owner (required), repo (required), issue_number (required), body (required). Returns: object

add_comment_on_prA

Add a comment to a pull request's discussion thread.

Posts to /repos/{owner}/{repo}/issues/{pull_number}/comments — Gitea's issue-comments endpoint also serves PR conversation comments (PRs and issues share the number namespace and comment infrastructure). For inline diff-line review comments, a separate /pulls/{n}/reviews-based tool would be needed; that's deliberately out of scope here.

Inputs: owner (required), repo (required), pull_number (required), body (required). Returns: object

commit_changesA
Destructive

Create or update a single file on a branch in one commit.

Auto-detects whether the file exists:

  • File does not exist on the branch: Gitea returns 404 to the SHA lookup; we POST to create the file.

  • File exists: we use its current SHA and PUT to update it.

Returns Gitea's FileResponse shape (the resulting commit + content metadata). Raises :class:GiteaAPIError on conflicts (e.g. concurrent update changed the SHA between our lookup and our write — caller should re-read and retry).

Single-file only. Multi-file commits would require Gitea's Git Trees API and are deliberately out of scope for this tool.

Inputs: owner (required), repo (required), branch (required), path (required), +2 more. Returns: object

create_branchA

Create a new branch in a repository.

Returns the created Gitea Branch object. Fails cleanly via :class:GiteaAPIError if the new branch name already exists.

Inputs: owner (required), repo (required), new_branch_name (required), old_branch_name. Returns: object

create_issueA

Create a new issue in a Gitea repository.

Returns the full Gitea Issue object including the assigned number, URL, and metadata. Label names are resolved to IDs against the repository's label set; an unknown label name fails the call cleanly with the list of valid names.

Inputs: owner (required), repo (required), title (required), body, +3 more. Returns: object

create_prA

Open a new pull request from head into base.

Returns the created Gitea PullRequest object (including the assigned number, URL, and merge status). Raises :class:GiteaAPIError if the head branch doesn't exist, there are no commits between head and base, or an open PR already exists for this branch pair.

Inputs: owner (required), repo (required), head (required), base (required), +3 more. Returns: object

create_releaseA

Create a new release in a repository.

.. warning::

Side effects: if tag_name does not already exist in the repository, Gitea creates the tag at the current target_commitish (or default branch). Creating a draft does NOT skip tag creation — both drafts and published releases will leave a tag in the repo.

Inputs: owner (required), repo (required), tag_name (required), name (required), +4 more. Returns: object

get_issueA
Read-only

Get a single issue by number, including all of its comments.

The returned object is the standard Gitea Issue payload, with an additional comments_list field containing the full list of Comment objects. The existing top-level comments integer field (comment count) is preserved.

Inputs: owner (required), repo (required), issue_number (required). Returns: object

get_pull_requestA
Read-only

Get a single pull request by number, including its discussion comments.

Mirrors :func:gitea_mcp.tools.issues.get_issue's shape: returns the full Gitea PullRequest object with an additional comments_list field containing the issue-style comment thread. Inline review comments (those attached to specific diff lines) are NOT included — those live under /pulls/{n}/reviews and are out of scope for this tool.

Inputs: owner (required), repo (required), pull_number (required). Returns: object

get_server_infoA
Read-only

Return information about the running gitea-mcp server and its Gitea connection.

Performs two Gitea API calls — GET /user (to identify the authenticated user the PAT belongs to) and GET /version (to report the Gitea instance version). If /version is unavailable (older Gitea, or the PAT lacks the scope), gitea_version falls back to None rather than raising.

Returns a dict with:

  • gitea_mcp_version — the gitea-mcp package version (e.g. "0.4.1").

  • gitea_url — the Gitea base URL this server is configured against.

  • gitea_user — the login of the authenticated Gitea user.

  • gitea_version — the Gitea instance version string, or None if unavailable.

Inputs: no named parameters. Returns: object

get_server_versionA
Read-only

Return the running gitea-mcp server's version.

No network call — just reports the package version. openWorldHint is False for this tool only, since it doesn't touch the Gitea instance or any external system.

Inputs: no named parameters. Returns: object

list_branchesA
Read-only

List branches in a repository.

Returns the standard Gitea Branch object array: [{name, commit: {id, ...}, protected, ...}]. Useful for inspecting available targets before creating a release, opening a PR, or filing a fix against a specific branch.

Inputs: owner (required), repo (required), page, limit. Returns: Generic wrapper for non-object return types.

list_issuesA
Read-only

List issues in a Gitea repository.

Pull requests are excluded; only true issues are returned. Filters compose (state AND labels AND assignee).

Inputs: owner (required), repo (required), state, labels, +3 more. Returns: Generic wrapper for non-object return types.

list_labelsA
Read-only

List labels defined in a repository.

Returns the standard Gitea Label object: {id, name, color, description, ...}. Use the id values when calling tools that take label_ids directly; most tools accept label names and resolve to IDs internally.

Inputs: owner (required), repo (required), page, limit. Returns: Generic wrapper for non-object return types.

list_milestonesA
Read-only

List milestones in a repository, optionally filtered by state.

Inputs: owner (required), repo (required), state, page, +1 more. Returns: Generic wrapper for non-object return types.

list_pull_requestsA
Read-only

List pull requests in a repository, optionally filtered by state.

Returns Gitea PullRequest objects (not Issue-style — the PR endpoint returns richer head/base/mergeable info than the issues endpoint does even when issues are filtered to type=pulls).

Inputs: owner (required), repo (required), state, sort, +2 more. Returns: Generic wrapper for non-object return types.

list_releasesA
Read-only

List releases for a repository.

Returns the standard Gitea Release object array, including drafts and pre-releases. Sort order is newest first.

Inputs: owner (required), repo (required), page, limit. Returns: Generic wrapper for non-object return types.

list_reposA
Read-only

List repositories.

Three modes:

  • owner empty: returns repositories accessible to the authenticated user (GET /user/repos).

  • owner is a user: returns that user's repositories (GET /users/{owner}/repos).

  • owner is an organization: returns that org's repositories (GET /orgs/{owner}/repos — automatically tried as a fallback when the user endpoint 404s, so callers don't need to know which it is).

Inputs: owner, page, limit. Returns: Generic wrapper for non-object return types.

merge_prA
Destructive

Merge a pull request.

Calls POST /repos/{owner}/{repo}/pulls/{pull_number}/merge using the requested merge strategy and optional commit-message overrides. This is tagged destructiveHint=True because it changes repository history and closes the pull request.

Inputs: owner (required), repo (required), pull_number (required), do, +2 more. Returns: object

read_fileA
Read-only

Read a file's content from a Gitea repository.

Returns Gitea's ContentsResponse shape extended with a text field containing the decoded file content as a UTF-8 string (or None if the content isn't valid UTF-8 — binary file). The raw base64 content and Gitea's encoding are preserved so callers can re-decode if needed.

The sha field in the response is what :func:commit_changes would need to update this file — but commit_changes fetches it internally, so callers don't usually need to pass it forward.

Inputs: owner (required), repo (required), path (required), ref. Returns: object

update_issueA
DestructiveIdempotent

Update an existing issue's title, body, state, assignees, milestone, or labels.

Each argument is independent — pass only the fields you want to change. Labels are replaced atomically against the new set (passing [] removes all labels). Other list fields (assignees) follow the same replace semantics.

Inputs: owner (required), repo (required), issue_number (required), title, +5 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action, with clear documentation differentiating similar tools like add_comment and add_comment_on_pr. No overlapping purposes that would cause agent misselection.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_branch, list_issues, merge_pr). The pattern is predictable and uniform across the entire set.

    Tool Count4/5

    With 21 tools, the count is slightly above the ideal 3-15 range but justified by the broad domain of Gitea repository management. The tools cover a comprehensive set of operations without being excessive.

    Completeness3/5

    The tool surface covers core CRUD for issues and PRs but has notable gaps: no update for PRs, no delete operations for any resource, and no management tools for labels or milestones. Some gaps are acknowledged as out of scope, but the set is not fully comprehensive.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides tools for interacting with the GitHub API, enabling AI assistants to query repositories, pull requests, issues, commits, users, and more.
      497 npm
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with GitHub via a fine-grained personal access token — pushing commits, managing branches, opening and merging PRs, creating issues, and reading repositories. It runs locally with no telemetry and supports a read-only mode.
      15
      1
      MIT