{
  "markdown": "# gitea-mcp\n\n<!-- mcp-name: io.github.werebear73/gitea-mcp -->\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for [Gitea](https://gitea.io) — 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.\n\nAlso works against **[Forgejo](https://forgejo.org)** and **[Codeberg](https://codeberg.org)** (API-compatible).\n\n## Why\n\nSelf-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:\n\n- File audit findings or refactor notes as Gitea issues without you leaving the chat\n- Triage a repo's open issues in natural language\n- Cut a release at the end of a coding session\n- Comment on issues across multiple repos in one pass\n\n## Features\n\n| Resource | Tools |\n| --- | --- |\n| Issues | `create_issue`, `list_issues`, `get_issue`, `update_issue`, `add_comment` |\n| Repos | `list_repos`, `list_labels`, `list_milestones`, `list_branches` |\n| Pulls | `list_pull_requests`, `get_pull_request`, `add_comment_on_pr`, `create_pr`, `merge_pr` |\n| Files | `read_file`, `commit_changes`, `create_branch` |\n| Releases | `list_releases`, `create_release` |\n| Meta | `get_server_info`, `get_server_version` |\n\n- Bearer authentication via Personal Access Token (PAT)\n- Async HTTP via `httpx` and `FastMCP`\n- Works with self-hosted Gitea, Forgejo, and Codeberg\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install gitea-mcp\n```\n\nOr with [`uv`](https://docs.astral.sh/uv/):\n\n```bash\nuv pip install gitea-mcp\n```\n\n### 2. Generate a Personal Access Token\n\nIn your Gitea instance, go to **Settings → Applications → Generate New Token** and grant at least:\n\n- `read:repository`\n- `write:issue`\n- `read:user`\n\nAdd `write:repository` if you also want to create releases.\n\n### 3. Configure your MCP client\n\n**Claude Desktop (interactive):** run\n\n```bash\ngitea-mcp init\n```\n\nIt 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.\n\nTo check that the server can reach your Gitea instance at any time:\n\n```bash\ngitea-mcp doctor\n```\n\n`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.\n\n**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):\n\n```json\n{\n  \"mcpServers\": {\n    \"gitea\": {\n      \"command\": \"uvx\",\n      \"args\": [\"gitea-mcp\"],\n      \"env\": {\n        \"GITEA_URL\": \"https://your-gitea-instance.example.com\",\n        \"GITEA_TOKEN\": \"your-personal-access-token\"\n      }\n    }\n  }\n}\n```\n\nIf 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.\n\nSee [`mcp.json`](mcp.json) for a complete example. The same shape works for Claude Desktop, VS Code, Cowork, Claude Code, and any other MCP-compatible client.\n\n## Configuration\n\nConfiguration is read from environment variables.\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `GITEA_URL` | Yes | — | Base URL of your Gitea instance (e.g., `https://gitea.example.com`) |\n| `GITEA_TOKEN` | Yes | — | Personal Access Token from your Gitea user settings |\n| `GITEA_TIMEOUT` | No | `30` | HTTP request timeout in seconds |\n| `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. |\n| `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. |\n\n## Self-hosting / HTTP transport\n\nBy 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:\n\n```bash\ngitea-mcp serve --transport http --host 0.0.0.0 --port 8000 --path /mcp\n```\n\nAll four flags can also be provided via environment variables (handy for Docker / systemd units):\n\n| Variable                  | Default      | Flag           |\n| ------------------------- | ------------ | -------------- |\n| `GITEA_MCP_TRANSPORT`     | `stdio`      | `--transport`  |\n| `GITEA_MCP_HOST`          | `127.0.0.1`  | `--host`       |\n| `GITEA_MCP_PORT`          | `8000`       | `--port`       |\n| `GITEA_MCP_PATH`          | `/mcp`       | `--path`       |\n\nMCP 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.\n\n**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.\n\nThe 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.\n\n## Compatibility\n\n| Server | Status |\n| --- | --- |\n| Gitea (self-hosted) | ✅ Primary target |\n| Forgejo | ✅ Expected to work (API-compatible) |\n| Codeberg | ✅ Expected to work (Codeberg runs Forgejo) |\n\n## Development\n\n```bash\ngit clone https://github.com/werebear73/gitea-mcp.git\ncd gitea-mcp\npip install -e \".[dev]\"\npre-commit install                       # commit-stage hooks (ruff + mypy)\npre-commit install --hook-type pre-push  # push-stage hooks (pytest + build check)\npytest\n```\n\nThe 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.\n\n## Roadmap\n\nSee [`docs/ROADMAP.md`](docs/ROADMAP.md) for what's shipped, what's next, and what's out of scope.\n\n## Publishing\n\n- MCP Registry metadata is tracked in [`server.json`](server.json).\n- Smithery + MCP Registry publication steps are documented in [`docs/PUBLISHING.md`](docs/PUBLISHING.md).\n\n## Versioning\n\nSemantic versioning, derived from git tags via `setuptools_scm`. See [`VERSIONING.md`](VERSIONING.md) for the release process.\n\n## Contributing\n\nIssues and pull requests welcome. For substantial changes, please open an issue first to discuss the approach.\n\n## License\n\n[MIT](LICENSE) — use it however you like, including commercial products.\n\n---\n\nBuilt by [Waretech Services](https://waretech.services).\n",
  "bytes": 7378,
  "sha": "89b471b9c53e6971c00fcb0488f3e790048aec86512af4f826ba2ce1736f152c",
  "repo_slug": "werebear73/gitea-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_werebear73_gitea_mcp_abcad4f3/readme"
}