Server data from the Official MCP Registry
Model Context Protocol server for Gitea (and Forgejo, Codeberg).
Model Context Protocol server for Gitea (and Forgejo, Codeberg).
gitea-mcp is a well-structured MCP server with proper Bearer token authentication via environment variables and comprehensive input validation. The codebase demonstrates good security practices including no hardcoded credentials, safe HTTP client configuration with retry logic, and appropriate permission scoping. Minor code quality observations exist but do not indicate genuine security vulnerabilities. Supply chain analysis found 6 known vulnerabilities in dependencies (1 critical, 3 high severity). Package verification found 1 issue.
6 files analyzed · 11 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: GITEA_URL
Environment variable: GITEA_TOKEN
Environment variable: GITEA_TIMEOUT
Environment variable: GITEA_MAX_RETRIES
Environment variable: GITEA_RETRY_BASE_DELAY
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-werebear73-gitea-mcp": {
"env": {
"GITEA_URL": "your-gitea-url-here",
"GITEA_TOKEN": "your-gitea-token-here",
"GITEA_TIMEOUT": "your-gitea-timeout-here",
"GITEA_MAX_RETRIES": "your-gitea-max-retries-here",
"GITEA_RETRY_BASE_DELAY": "your-gitea-retry-base-delay-here"
},
"args": [
"gitea-mcp"
],
"command": "uvx"
}
}
}From the project's GitHub README.
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).
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:
| 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 |
| Meta | get_server_info, get_server_version |
httpx and FastMCPpip install gitea-mcp
Or with uv:
uv pip install gitea-mcp
In your Gitea instance, go to Settings → Applications → Generate New Token and grant at least:
read:repositorywrite:issueread:userAdd write:repository if you also want to create releases.
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 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. |
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):
| 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.
| Server | Status |
|---|---|
| Gitea (self-hosted) | ✅ Primary target |
| Forgejo | ✅ Expected to work (API-compatible) |
| Codeberg | ✅ Expected to work (Codeberg runs Forgejo) |
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.
See docs/ROADMAP.md for what's shipped, what's next, and what's out of scope.
server.json.docs/PUBLISHING.md.Semantic versioning, derived from git tags via setuptools_scm. See VERSIONING.md for the release process.
Issues and pull requests welcome. For substantial changes, please open an issue first to discuss the approach.
MIT — use it however you like, including commercial products.
Built by Waretech Services.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.