gitea-mcp
API-compatible with Gitea; provides tools for managing issues, repositories, pull requests, files, and releases on Codeberg (which runs Forgejo) instances.
API-compatible with Gitea; provides tools for managing issues, repositories, pull requests, files, and releases on Forgejo instances.
Provides tools for managing issues, repositories, pull requests, files, and releases on Gitea instances.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gitea-mcp list open issues in my repo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 and Codeberg (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
Related MCP server: forgejo-mcp
Features
Resource | Tools |
Issues |
|
Repos |
|
Pulls |
|
Files |
|
Releases |
|
Meta |
|
Bearer authentication via Personal Access Token (PAT)
Async HTTP via
httpxandFastMCPWorks with self-hosted Gitea, Forgejo, and Codeberg
Quick Start
1. Install
pip install gitea-mcpOr with uv:
uv pip install gitea-mcp2. Generate a Personal Access Token
In your Gitea instance, go to Settings → Applications → Generate New Token and grant at least:
read:repositorywrite:issueread:user
Add write:repository if you also want to create releases.
3. Configure your MCP client
Claude Desktop (interactive): run
gitea-mcp initIt 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 doctordoctor 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.
Variable | Required | Default | Description |
| Yes | — | Base URL of your Gitea instance (e.g., |
| Yes | — | Personal Access Token from your Gitea user settings |
| No |
| HTTP request timeout in seconds |
| No |
| Max retries for transient failures on idempotent methods ( |
| No |
| Base delay (seconds) for exponential backoff between retries. Effective delay grows as |
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 /mcpAll four flags can also be provided via environment variables (handy for Docker / systemd units):
Variable | Default | Flag |
|
|
|
|
|
|
|
|
|
|
|
|
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
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)
pytestThe 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.
Available Tools
21 toolsadd_commentB
Add a comment to an existing issue. Returns the created Comment object.
Inputs: owner (required), repo (required), issue_number (required), body (required). Returns: object
add_comment_on_prA
Add a comment to a pull request's discussion thread.
Posts to /repos/{owner}/{repo}/issues/{pull_number}/comments — Gitea's
issue-comments endpoint also serves PR conversation comments (PRs and
issues share the number namespace and comment infrastructure). For inline
diff-line review comments, a separate /pulls/{n}/reviews-based tool
would be needed; that's deliberately out of scope here.
Inputs: owner (required), repo (required), pull_number (required), body (required). Returns: object
commit_changesADestructive
Create or update a single file on a branch in one commit.
Auto-detects whether the file exists:
File does not exist on the branch: Gitea returns 404 to the SHA lookup; we
POSTto create the file.File exists: we use its current SHA and
PUTto update it.
Returns Gitea's FileResponse shape (the resulting commit + content
metadata). Raises :class:GiteaAPIError on conflicts (e.g. concurrent
update changed the SHA between our lookup and our write — caller should
re-read and retry).
Single-file only. Multi-file commits would require Gitea's Git Trees API and are deliberately out of scope for this tool.
Inputs: owner (required), repo (required), branch (required), path (required), +2 more. Returns: object
create_branchA
Create a new branch in a repository.
Returns the created Gitea Branch object. Fails cleanly via
:class:GiteaAPIError if the new branch name already exists.
Inputs: owner (required), repo (required), new_branch_name (required), old_branch_name. Returns: object
create_issueA
Create a new issue in a Gitea repository.
Returns the full Gitea Issue object including the assigned number, URL, and metadata. Label names are resolved to IDs against the repository's label set; an unknown label name fails the call cleanly with the list of valid names.
Inputs: owner (required), repo (required), title (required), body, +3 more. Returns: object
create_prA
Open a new pull request from head into base.
Returns the created Gitea PullRequest object (including the assigned
number, URL, and merge status). Raises :class:GiteaAPIError if the
head branch doesn't exist, there are no commits between head and base,
or an open PR already exists for this branch pair.
Inputs: owner (required), repo (required), head (required), base (required), +3 more. Returns: object
create_releaseA
Create a new release in a repository.
.. warning::
Side effects: if tag_name does not already exist in the repository,
Gitea creates the tag at the current target_commitish (or default
branch). Creating a draft does NOT skip tag creation — both drafts and
published releases will leave a tag in the repo.
Inputs: owner (required), repo (required), tag_name (required), name (required), +4 more. Returns: object
get_issueARead-only
Get a single issue by number, including all of its comments.
The returned object is the standard Gitea Issue payload, with an additional
comments_list field containing the full list of Comment objects. The
existing top-level comments integer field (comment count) is preserved.
Inputs: owner (required), repo (required), issue_number (required). Returns: object
get_pull_requestARead-only
Get a single pull request by number, including its discussion comments.
Mirrors :func:gitea_mcp.tools.issues.get_issue's shape: returns the full
Gitea PullRequest object with an additional comments_list field
containing the issue-style comment thread. Inline review comments (those
attached to specific diff lines) are NOT included — those live under
/pulls/{n}/reviews and are out of scope for this tool.
Inputs: owner (required), repo (required), pull_number (required). Returns: object
get_server_infoARead-only
Return information about the running gitea-mcp server and its Gitea connection.
Performs two Gitea API calls — GET /user (to identify the authenticated
user the PAT belongs to) and GET /version (to report the Gitea instance
version). If /version is unavailable (older Gitea, or the PAT lacks the
scope), gitea_version falls back to None rather than raising.
Returns a dict with:
gitea_mcp_version— the gitea-mcp package version (e.g."0.4.1").gitea_url— the Gitea base URL this server is configured against.gitea_user— theloginof the authenticated Gitea user.gitea_version— the Gitea instance version string, orNoneif unavailable.
Inputs: no named parameters. Returns: object
get_server_versionARead-only
Return the running gitea-mcp server's version.
No network call — just reports the package version. openWorldHint is
False for this tool only, since it doesn't touch the Gitea instance
or any external system.
Inputs: no named parameters. Returns: object
list_branchesARead-only
List branches in a repository.
Returns the standard Gitea Branch object array: [{name, commit: {id, ...}, protected, ...}]. Useful for inspecting available targets before creating
a release, opening a PR, or filing a fix against a specific branch.
Inputs: owner (required), repo (required), page, limit. Returns: Generic wrapper for non-object return types.
list_issuesARead-only
List issues in a Gitea repository.
Pull requests are excluded; only true issues are returned. Filters compose (state AND labels AND assignee).
Inputs: owner (required), repo (required), state, labels, +3 more. Returns: Generic wrapper for non-object return types.
list_labelsARead-only
List labels defined in a repository.
Returns the standard Gitea Label object: {id, name, color, description, ...}.
Use the id values when calling tools that take label_ids directly;
most tools accept label names and resolve to IDs internally.
Inputs: owner (required), repo (required), page, limit. Returns: Generic wrapper for non-object return types.
list_milestonesARead-only
List milestones in a repository, optionally filtered by state.
Inputs: owner (required), repo (required), state, page, +1 more. Returns: Generic wrapper for non-object return types.
list_pull_requestsARead-only
List pull requests in a repository, optionally filtered by state.
Returns Gitea PullRequest objects (not Issue-style — the PR endpoint
returns richer head/base/mergeable info than the issues endpoint does
even when issues are filtered to type=pulls).
Inputs: owner (required), repo (required), state, sort, +2 more. Returns: Generic wrapper for non-object return types.
list_releasesARead-only
List releases for a repository.
Returns the standard Gitea Release object array, including drafts and pre-releases. Sort order is newest first.
Inputs: owner (required), repo (required), page, limit. Returns: Generic wrapper for non-object return types.
list_reposARead-only
List repositories.
Three modes:
ownerempty: returns repositories accessible to the authenticated user (GET /user/repos).owneris a user: returns that user's repositories (GET /users/{owner}/repos).owneris an organization: returns that org's repositories (GET /orgs/{owner}/repos— automatically tried as a fallback when the user endpoint 404s, so callers don't need to know which it is).
Inputs: owner, page, limit. Returns: Generic wrapper for non-object return types.
merge_prADestructive
Merge a pull request.
Calls POST /repos/{owner}/{repo}/pulls/{pull_number}/merge using the
requested merge strategy and optional commit-message overrides. This is
tagged destructiveHint=True because it changes repository history and
closes the pull request.
Inputs: owner (required), repo (required), pull_number (required), do, +2 more. Returns: object
read_fileARead-only
Read a file's content from a Gitea repository.
Returns Gitea's ContentsResponse shape extended with a text field
containing the decoded file content as a UTF-8 string (or None if the
content isn't valid UTF-8 — binary file). The raw base64 content and
Gitea's encoding are preserved so callers can re-decode if needed.
The sha field in the response is what :func:commit_changes would
need to update this file — but commit_changes fetches it internally,
so callers don't usually need to pass it forward.
Inputs: owner (required), repo (required), path (required), ref. Returns: object
update_issueADestructiveIdempotent
Update an existing issue's title, body, state, assignees, milestone, or labels.
Each argument is independent — pass only the fields you want to change.
Labels are replaced atomically against the new set (passing [] removes
all labels). Other list fields (assignees) follow the same replace semantics.
Inputs: owner (required), repo (required), issue_number (required), title, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct resource or action, with clear documentation differentiating similar tools like add_comment and add_comment_on_pr. No overlapping purposes that would cause agent misselection.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_branch, list_issues, merge_pr). The pattern is predictable and uniform across the entire set.
With 21 tools, the count is slightly above the ideal 3-15 range but justified by the broad domain of Gitea repository management. The tools cover a comprehensive set of operations without being excessive.
The tool surface covers core CRUD for issues and PRs but has notable gaps: no update for PRs, no delete operations for any resource, and no management tools for labels or milestones. Some gaps are acknowledged as out of scope, but the set is not fully comprehensive.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
A MCP server built for developers enabling Git based project management with project and personal…
Create, deploy, and operate MCP servers directly from your GitHub repositories.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for the GitCode API, enabling AI assistants to interact with GitCode repositories, issues, pull requests, and more.1MIT
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server for Forgejo and Gitea instances, enabling AI assistants to interact with repositories, issues, pull requests, and more.10017MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides tools for interacting with the GitHub API, enabling AI assistants to query repositories, pull requests, issues, commits, users, and more.497 npmISC
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to interact with GitHub via a fine-grained personal access token — pushing commits, managing branches, opening and merging PRs, creating issues, and reading repositories. It runs locally with no telemetry and supports a read-only mode.151MIT