Provides tools for interacting with a Gitea instance, including listing repositories, managing issues, checking CI/CD workflow runs, creating branches, committing files, and opening pull requests.
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 Server list open issues in the web-app repository"
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.
A Model Context Protocol (MCP) server that empowers AI agents to interact with a Gitea version control instance.
This server provides tools that allow LLMs (via clients like Claude Desktop or autonomous agents) to read repositories, manage issues, trigger workflows, and even commit code directly to your self-hosted Gitea instance.
Repository Management: List accessible repositories.
Issue Tracking: Read existing issues and create new ones.
CI/CD Integration: Check the status of recent Gitea Actions workflow runs.
Code Modification: Create branches, open Pull Requests, and commit multiple files directly via the Gitea API.
Related MCP server: GitHub MCP Server
Python 3.10+
uv for dependency management.
A running Gitea instance.
A Gitea Personal Access Token (Settings -> Applications -> Generate Token). See the Gitea documentation for more details.
Clone the repository and run uv sync to install dependencies and set up the virtual environment:
git clone https://github.com/your-username/mcp-servers.git
cd mcp-servers
uv sync(Note: Consider extracting gitea_mcp.py to its own repository if you plan to build more MCP servers).
The server requires two environment variables to connect to your Gitea instance:
GITEA_URL: The URL of your Gitea instance (e.g., http://gitea.local:3000).
GITEA_TOKEN: Your Personal Access Token.
Using a .env file (Recommended):
To avoid having to set these variables every time, you can create a .env file in the root of the project. Many tools (including python-dotenv) will automatically load these:
GITEA_URL="http://your-gitea-instance:3000"
GITEA_TOKEN="your_personal_access_token"You can run the server directly via Python using uv run:
If you choose to set the variables directly in your terminal using export, note that this is only viable for the life of that specific shell session:
export GITEA_URL="http://your-gitea-instance:3000"
export GITEA_TOKEN="your_personal_access_token"
uv run gitea_mcp.pyBecause MCP is a standardized protocol, you can use this server with any compatible client. Below are configuration examples for a few popular clients.
You can integrate this server into a Hermes agent. By running hermes config edit, you can set the path and the tool name for the agent in your configuration:
Option 1: Using uv directly (Recommended)
mcp_servers:
gitea-local:
command: uv
args:
- --directory
- /absolute/path/to/mcp-servers
- run
- gitea_mcp.py
env:
GITEA_URL: http://<your-instance>:3000/
GITEA_TOKEN: <your-PAT>Option 2: Using the explicit virtual environment Python
mcp_servers:
gitea-local:
command: /absolute/path/to/mcp-servers/.venv/bin/python
args:
- /absolute/path/to/mcp-servers/gitea_mcp.py
env:
GITEA_URL: http://<your-instance>:3000/
GITEA_TOKEN: <your-PAT>To use this with an MCP-compatible client like Claude Desktop, you would add it to your configuration file (usually claude_desktop_config.json). Make sure to specify the absolute path to the Python executable within your environment:
{
"mcpServers": {
"gitea": {
"command": "/absolute/path/to/mcp-servers/.venv/bin/python",
"args": ["/absolute/path/to/mcp-servers/gitea_mcp.py"],
"env": {
"GITEA_URL": "http://your-gitea-instance:3000",
"GITEA_TOKEN": "your_personal_access_token"
}
}
}
}list_repositories: Lists all repositories accessible by the configured user.
list_issues: Fetches open or closed issues for a specific repository.
create_issue: Opens a new issue in a repository.
list_workflow_runs: Lists recent Gitea Actions CI/CD pipeline runs.
create_branch: Creates a new branch from a specified base branch.
commit_files: Commits a list of file changes (creations or updates) directly to a branch (automatically handles base64 encoding).
create_pull_request: Opens a PR from a feature branch to a base branch.
This project is licensed under the MIT License - see the LICENSE file for details.
Commits file creations or updates to a Gitea repository via API.
files_to_change should be a list of dicts: [{"path": "src/main.py", "content": "print('hello')"}]
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| owner | Yes | ||
| branch | Yes | ||
| message | Yes | ||
| files_to_change | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a mutation ('commits') and hints at upsert semantics ('creations or updates'), but says nothing about authentication needs, whether files are overwritten or merged, whether an existing commit is amended, or what happens on branch conflicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the purpose and followed by the trickiest parameter's format. The example earns its place, though the description could still be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. For a five-parameter mutation tool with no annotations, the description covers the hard-to-guess parameter but leaves the mutation's behavioral profile (auth, overwrite semantics, failure modes) unaddressed, making it only minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across five required parameters, so the description is the only source of parameter meaning. It does add real value by specifying the exact dict shape and an example for files_to_change, but owner, repo, branch, and message remain undocumented beyond their self-evident names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (commits) and resource (file creations or updates to a Gitea repository), which is enough to distinguish it from siblings like create_branch or create_pull_request. It does not explicitly name those siblings, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus create_branch, create_pull_request, or any alternative. No prerequisites (auth, branch existence) or exclusions are given. The agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new branch in a Gitea repository from a source branch.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| owner | Yes | ||
| source_branch | No | main | |
| new_branch_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses only that a branch is created, omitting permissions, branch-exists behavior, source-branch defaulting, and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the action and resource stated immediately. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and 0% parameter documentation, the description omits auth needs, branch-exists behavior, and parameter roles. The output schema covers return values, but the call context remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for four parameters. The description vaguely references a source branch and repository but does not name or explain owner, repo, new_branch_name, or the default 'main' source branch.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Creates') and resource ('new branch') in a Gitea repository, adding 'from a source branch' to clarify the operation. It does not explicitly differentiate from siblings, but branch creation is distinct from issue, PR, and file tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no when-to-use guidance, no alternatives, and no prerequisites. Creation is implied by the verb, but all usage conditions are left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new issue in a Gitea repository.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| repo | Yes | ||
| owner | Yes | ||
| title | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It only states that an issue is created and omits any mention of required permissions, side effects like notifications, or validation rules for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it is under-specified for a four-parameter mutation tool, so its brevity reflects incompleteness rather than optimal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, zero schema description coverage, and a mutation operation, the description is incomplete. While an output schema exists and covers return values, the description still fails to explain permissions, parameter usage, or when to choose this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage across four parameters, and the description does not explain any of them. It gives no meaning to owner, repo, title, or body beyond the vague phrase 'in a Gitea repository.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Creates a new issue in a Gitea repository.' This distinguishes it implicitly from siblings like create_pull_request and create_branch. However, it does not explicitly differentiate itself from other creation tools or state its scope boundaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_pull_request or list_issues. It merely states what the tool does, leaving usage context entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new pull request in a Gitea repository.
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | main | |
| body | No | ||
| head | Yes | ||
| repo | Yes | ||
| owner | Yes | ||
| title | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the mutation action ('Creates') but does not disclose authentication requirements, whether the operation fails if a PR already exists, what happens to existing refs, or any other side effects. It is minimally informative but far from complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words, which is structurally clean. However, it is so terse that it omits essential information, making the conciseness feel more like under-specification than efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists (so return values need not be explained), the tool has six parameters with zero schema coverage and no annotations. The description fails to compensate by explaining parameter semantics, prerequisites, or behavior. For a create operation with this many inputs, it is substantially incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for all six parameters, and the description mentions none of them. Critical fields like 'head', 'base', 'owner', and 'repo' are left entirely unexplained, including which are required and what format they expect. The description adds no meaning beyond the bare parameter names in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Creates a new pull request') plus the platform ('Gitea repository'), so the agent knows exactly what operation is performed. Sibling tools include other create operations but no other pull-request creation, so explicit sibling differentiation is not needed. The only gap is that scope details like owner/repo are not mentioned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, no prerequisites (e.g., branch must exist), and no mention of related operations like create_branch or commit_files. It simply declares what it does without any contextual routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches issues for a specific repository (state can be 'open', 'closed', or 'all').
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| owner | Yes | ||
| state | No | open |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only implies a read operation via 'fetches' and says nothing about pagination, rate limits, authentication requirements, or whether results are filtered by the caller's permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the resource and filter front-loaded and no filler. The parenthetical state values are the one piece of genuinely load-bearing detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be described, but for a read tool with zero annotations and zero schema coverage the description leaves auth, pagination, ordering, and the owner parameter unaddressed. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It usefully enumerates the allowed state values ('open', 'closed', 'all') that the schema does not document as an enum, and ties repo to a 'specific repository', but adds nothing about the owner parameter or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (fetches) and resource (issues) scoped to a specific repository, and enumerates the state values. It is clear on its own, though it does not explicitly distinguish itself from siblings like list_repositories or list_workflow_runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as create_issue or list_repositories. The state filter implies a listing use case but there are no exclusions, prerequisites, or routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all repositories accessible by the current Gitea user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It states the result is scoped to repositories the current user can access, which is useful, but it says nothing about pagination, result limits, ordering, or that the operation is read-only — all of which an agent would benefit from knowing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word contributes to defining purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with an output schema covering return values, the description is nearly sufficient. The main missing piece is pagination/result-scope behavior, but the output schema absorbs most of the completeness burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; there are no parameter semantics to clarify beyond what the empty schema already communicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource (lists repositories) plus a clear scope qualifier (accessible by the current Gitea user), so an agent can distinguish it from list_issues or list_workflow_runs. It lacks any explicit callout of sibling differences, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no exclusions. Usage context is only implied by the tool name and scope phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists recent Gitea Actions CI/CD workflow runs for a repository.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| owner | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it only states that runs are 'recent' without defining that window, result limits, ordering, or pagination. For a list tool with zero annotation coverage, that is a significant disclosure gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with no padding and the resource front-loaded. It is appropriately sized, though the brevity is partly under-specification rather than disciplined concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, but with no annotations and 0% parameter coverage the description should still cover result scoping and parameter meaning. As written it leaves the agent guessing about limits, ordering, and parameter roles.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both required parameters, so the description must compensate. It mentions 'repository' generally but never clarifies the owner vs repo split or their expected format, leaving both parameters essentially undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('Lists... workflow runs') and scopes it to Gitea Actions CI/CD for a repository, which is clear enough that an agent can distinguish it from list_issues or list_repositories. It does not explicitly name a sibling alternative, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of pagination or time-window constraints despite 'recent' implying hidden filtering behavior. Usage must be entirely inferred from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0commit_filescreate_branchcreate_issuecreate_pull_requestlist_issueslist_repositorieslist_workflow_runsScored across 7 tools
Each tool targets a clearly distinct resource and action: listing repositories, managing issues (list/create), workflow runs, branches, pull requests, and file commits. No two tools share overlapping purposes.
All tools follow a consistent verb_noun snake_case pattern (list_repositories, create_issue, create_pull_request, commit_files). The convention is uniform throughout the set.
Seven tools is well-scoped for a Gitea integration, covering core repository, issue, CI, branch, PR, and file operations without bloat.
The surface is write-heavy and lacks lifecycle coverage: issues have list+create but no get/update/close, PRs can only be created (no get/list/merge), and branches/files have no read or delete operations. Notable gaps that would block common workflows.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Git-backed platform for skills, tools, and context for AI agents
Access the GitHub API, enabling file operations, repository management, search functionality, and…
