opc/gitea_mcp
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0e7e83fe8b263772c3543a99b44a130e440b8800
gitea_mcp/package/gitea_mcp-0.5.2.dev4.dist-info/METADATA
T
QiuSW 0e7e83fe8b Initial commit
2026-08-07 22:18:16 +08:00

214 lines
8.9 KiB
Plaintext
Raw Blame History

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).
Reference in New Issue View Git Blame Copy Permalink