gitea-mcp

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](https://forgejo.org) and [Codeberg](https://codeberg.org) (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

• 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.

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

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

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

• MCP Registry metadata is tracked in server.json.
• Smithery + MCP Registry publication steps are documented in docs/PUBLISHING.md.

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.