gitea-mcp

io.github.werebear73Published by GitHub account werebear73v0.5.1Updated Oct 25, 2026

Model Context Protocol server for Gitea (and Forgejo, Codeberg).

VerifiedSTDIODesktop onlyProductivity & WorkflowDeveloper Tools

Overview

AI-generated overview

Local MCP server that lets an AI assistant read, create and manage issues, pull requests, files and releases on a Gitea, Forgejo or Codeberg instance.

What you can do
Create, list, read, update and comment on issues, and list labels, milestones and branches for triage and notes. List and inspect pull requests, comment on them, create and merge them. Read repository files, commit changes and create branches. List and create releases. Report server info and version.
When to use it
Useful when your team or project tracks work on a self-hosted Gitea, Forgejo or Codeberg instance and you want the assistant to file issues, triage them, comment across repos, or cut a release without leaving the chat.
Requirements
Runs locally as a Python package (pip or uvx) over stdio, or self-hosted over streamable HTTP. Requires GITEA_URL (instance base URL) and GITEA_TOKEN (personal access token) as environment variables, plus network access to the instance. Optional GITEA_TIMEOUT, GITEA_MAX_RETRIES and GITEA_RETRY_BASE_DELAY tune HTTP behavior.
Before you install
GITEA_TOKEN is a personal access token granting the scopes you choose (read:repository, write:issue, read:user, and write:repository for releases); keep it out of shared configs. The assistant can write: create and update issues, comments, branches, commits, pull requests, merges and releases. In HTTP mode the server uses its own GITEA_TOKEN, so any client reaching the URL acts as that one user; restrict access.

Installation

In SourceWeft

  1. Open gitea-mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

Features

ResourceTools
Issuescreate_issue, list_issues, get_issue, update_issue, add_comment
Reposlist_repos, list_labels, list_milestones, list_branches
Pullslist_pull_requests, get_pull_request, add_comment_on_pr, create_pr, merge_pr
Filesread_file, commit_changes, create_branch
Releaseslist_releases, create_release
Metaget_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

bash
pip install gitea-mcp

Or with uv:

bash
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

bash
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:

bash
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):

json
{  "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.

VariableRequiredDefaultDescription
GITEA_URLYes—Base URL of your Gitea instance (e.g., https://gitea.example.com)
GITEA_TOKENYes—Personal Access Token from your Gitea user settings
GITEA_TIMEOUTNo30HTTP request timeout in seconds
GITEA_MAX_RETRIESNo3Max 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_DELAYNo0.5Base 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:

bash
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):

VariableDefaultFlag
GITEA_MCP_TRANSPORTstdio--transport
GITEA_MCP_HOST127.0.0.1--host
GITEA_MCP_PORT8000--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

ServerStatus
Gitea (self-hosted)✅ Primary target
Forgejo✅ Expected to work (API-compatible)
Codeberg✅ Expected to work (Codeberg runs Forgejo)

Development

bash
git clone https://github.com/werebear73/gitea-mcp.gitcd gitea-mcppip 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.

Source: README.md at commit 5adde5e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts