|
|
|
@@ -0,0 +1,213 @@
|
|
|
|
|
Metadata-Version: 2.4
|
|
|
|
|
Name: gitea-mcp
|
|
|
|
|
Version: 0.5.2.dev4
|
|
|
|
|
Summary: Model Context Protocol server for Gitea (and Forgejo, Codeberg).
|
|
|
|
|
Author-email: Sam Ware <samuel@waretech.services>
|
|
|
|
|
License: MIT
|
|
|
|
|
Project-URL: Homepage, https://github.com/werebear73/gitea-mcp
|
|
|
|
|
Project-URL: Issues, https://github.com/werebear73/gitea-mcp/issues
|
|
|
|
|
Project-URL: Source, https://github.com/werebear73/gitea-mcp
|
|
|
|
|
Keywords: mcp,gitea,forgejo,codeberg,model-context-protocol,llm,ai
|
|
|
|
|
Classifier: Development Status :: 3 - Alpha
|
|
|
|
|
Classifier: Intended Audience :: Developers
|
|
|
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
|
|
|
Classifier: Operating System :: OS Independent
|
|
|
|
|
Classifier: Programming Language :: Python :: 3
|
|
|
|
|
Classifier: Programming Language :: Python :: 3.11
|
|
|
|
|
Classifier: Programming Language :: Python :: 3.12
|
|
|
|
|
Classifier: Programming Language :: Python :: 3.13
|
|
|
|
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
|
|
|
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
|
|
|
Requires-Python: >=3.11
|
|
|
|
|
Description-Content-Type: text/markdown
|
|
|
|
|
License-File: LICENSE
|
|
|
|
|
Requires-Dist: fastmcp<3.0,>=2.0
|
|
|
|
|
Requires-Dist: httpx>=0.27.0
|
|
|
|
|
Requires-Dist: pydantic>=2.0.0
|
|
|
|
|
Provides-Extra: dev
|
|
|
|
|
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
|
|
|
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
|
|
|
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
|
|
|
|
|
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
|
|
|
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
|
|
|
Requires-Dist: pre-commit>=3.5; extra == "dev"
|
|
|
|
|
Requires-Dist: build>=1.0; extra == "dev"
|
|
|
|
|
Requires-Dist: twine>=5.0; extra == "dev"
|
|
|
|
|
Dynamic: license-file
|
|
|
|
|
|
|
|
|
|
# gitea-mcp
|
|
|
|
|
|
|
|
|
|
<!-- mcp-name: io.github.werebear73/gitea-mcp -->
|
|
|
|
|
|
|
|
|
|
A [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.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
| 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` |
|
|
|
|
|
| Wiki | `list_wiki_pages`, `get_wiki_page`, `list_wiki_revisions`, `create_wiki_page`, `update_wiki_page`, `delete_wiki_page` |
|
|
|
|
|
| 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
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
pip install gitea-mcp
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Or with [`uv`](https://docs.astral.sh/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 or write wiki pages.
|
|
|
|
|
|
|
|
|
|
### 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`](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:
|
|
|
|
|
|
|
|
|
|
```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):
|
|
|
|
|
|
|
|
|
|
| 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
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`](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`](server.json).
|
|
|
|
|
- Smithery + MCP Registry publication steps are documented in [`docs/PUBLISHING.md`](docs/PUBLISHING.md).
|
|
|
|
|
|
|
|
|
|
## Versioning
|
|
|
|
|
|
|
|
|
|
Semantic versioning, derived from git tags via `setuptools_scm`. See [`VERSIONING.md`](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](LICENSE) — use it however you like, including commercial products.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
Built by [Waretech Services](https://waretech.services).
|
QiuSW