mirror of
https://gitea.com/gitea/gitea-mcp.git
synced 2025-08-23 22:33:05 +00:00
0535f5bab7
- Add a "What is Gitea?" section explaining Gitea - Add a "What is MCP?" section describing Model Context Protocol - Reformat the MCP server configuration instructions for better readability - Correct the markdown table for tool support - Add a Troubleshooting section with common steps to resolve issues Signed-off-by: appleboy <appleboy.tw@gmail.com> Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/12 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: appleboy <appleboy.tw@gmail.com> Co-committed-by: appleboy <appleboy.tw@gmail.com>
144 lines
5.7 KiB
Markdown
144 lines
5.7 KiB
Markdown
# Gitea MCP Server
|
|
|
|
**Gitea MCP Server** is an integration plugin designed to connect Gitea with Model Context Protocol (MCP) systems. This allows for seamless command execution and repository management through an MCP-compatible chat interface.
|
|
|
|
## What is Gitea?
|
|
|
|
Gitea is a community-managed lightweight code hosting solution written in Go. It is published under the MIT license. Gitea provides Git hosting including a repository viewer, issue tracking, pull requests, and more.
|
|
|
|
## What is MCP?
|
|
|
|
Model Context Protocol (MCP) is a protocol that allows for the integration of various tools and systems through a chat interface. It enables seamless command execution and management of repositories, users, and other resources.
|
|
|
|
## 🚧 Installation
|
|
|
|
### 📥 Download the official binary release
|
|
|
|
You can download the official release from [here](https://gitea.com/gitea/gitea-mcp/releases).
|
|
|
|
### 🔧 Build from Source
|
|
|
|
You can download the source code by cloning the repository using Git:
|
|
|
|
```bash
|
|
git clone https://gitea.com/gitea/gitea-mcp.git
|
|
```
|
|
|
|
Before building, make sure you have the following installed:
|
|
|
|
- make
|
|
- Golang (Go 1.24 or later recommended)
|
|
|
|
Then run:
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
### 📁 Add to PATH
|
|
|
|
After building, copy the binary gitea-mcp to a directory included in your system's PATH. For example:
|
|
|
|
```bash
|
|
cp gitea-mcp /usr/local/bin/
|
|
```
|
|
|
|
## 🚀 Usage
|
|
|
|
This example is for Cursor, you can also use plugins in VSCode.
|
|
To configure the MCP server for Gitea, add the following to your MCP configuration file:
|
|
|
|
- **stdio mode**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"gitea": {
|
|
"command": "gitea-mcp",
|
|
"args": [
|
|
"-t",
|
|
"stdio",
|
|
"--host",
|
|
"https://gitea.com"
|
|
// "--token", "<your personal access token>"
|
|
],
|
|
"env": {
|
|
// "GITEA_HOST": "https://gitea.com",
|
|
"GITEA_ACCESS_TOKEN": "<your personal access token>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
- **sse mode**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"gitea": {
|
|
"url": "http://localhost:8080/sse"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
> [!NOTE]
|
|
> You can provide your Gitea host and access token either as command-line arguments or environment variables.
|
|
> Command-line arguments have the highest priority
|
|
|
|
Once everything is set up, try typing the following in your MCP-compatible chatbox:
|
|
|
|
```text
|
|
list all my repositories
|
|
```
|
|
|
|
## ✅ Available Tools
|
|
|
|
The Gitea MCP Server supports the following tools:
|
|
|
|
| Tool | Scope | Description |
|
|
| :--------------------------: | :----------: | :---------------------------------------------------: |
|
|
| get_my_user_info | User | Get the information of the authenticated user |
|
|
| create_repo | Repository | Create a new repository |
|
|
| fork_repo | Repository | Fork a repository |
|
|
| list_my_repos | Repository | List all repositories owned by the authenticated user |
|
|
| create_branch | Branch | Create a new branch |
|
|
| delete_branch | Branch | Delete a branch |
|
|
| list_branches | Branch | List all branches in a repository |
|
|
| list_repo_commits | Commit | List all commits in a repository |
|
|
| get_file_content | File | Get the content and metadata of a file |
|
|
| create_file | File | Create a new file |
|
|
| update_file | File | Update an existing file |
|
|
| delete_file | File | Delete a file |
|
|
| get_issue_by_index | Issue | Get an issue by its index |
|
|
| list_repo_issues | Issue | List all issues in a repository |
|
|
| create_issue | Issue | Create a new issue |
|
|
| create_issue_comment | Issue | Create a comment on an issue |
|
|
| get_pull_request_by_index | Pull Request | Get a pull request by its index |
|
|
| list_repo_pull_requests | Pull Request | List all pull requests in a repository |
|
|
| create_pull_request | Pull Request | Create a new pull request |
|
|
| search_users | User | Search for users |
|
|
| search_org_teams | Organization | Search for teams in an organization |
|
|
| search_repos | Repository | Search for repositories |
|
|
| get_gitea_mcp_server_version | Server | Get the version of the Gitea MCP Server |
|
|
|
|
## 🐛 Debugging
|
|
|
|
To enable debug mode, add the `-d` flag when running the Gitea MCP Server with sse mode:
|
|
|
|
```sh
|
|
./gitea-mcp -t sse [--port 8080] --token <your personal access token> -d
|
|
```
|
|
|
|
## 🛠 Troubleshooting
|
|
|
|
If you encounter any issues, here are some common troubleshooting steps:
|
|
|
|
1. **Check your PATH**: Ensure that the `gitea-mcp` binary is in a directory included in your system's PATH.
|
|
2. **Verify dependencies**: Make sure you have all the required dependencies installed, such as `make` and `Golang`.
|
|
3. **Review configuration**: Double-check your MCP configuration file for any errors or missing information.
|
|
4. **Consult logs**: Check the logs for any error messages or warnings that can provide more information about the issue.
|
|
|
|
Enjoy exploring and managing your Gitea repositories via chat!
|