# gitee-mcp

**Repository Path**: codelint/gitee-mcp

## Basic Information

- **Project Name**: gitee-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gitee MCP Server

基于 MCP (Model Context Protocol) 协议的服务器，为 Gitee 用户提供操作 Issues 的工具集。

## 功能特性

- **Issues CRUD**: 创建、查询、更新、列出 Gitee Issues
- **Issue 评论**: 创建和列出 Issue 评论
- **用户信息**: 获取当前用户的邮箱信息
- **标准 MCP 协议**: 支持 MCP HTTP 和 stdio 传输，兼容 JSON-RPC 2.0

## 技术架构

- **框架**: aiohttp (异步 HTTP 服务器) / 原生 stdio
- **协议**: MCP HTTP 传输 / MCP stdio 传输 (Model Context Protocol)
- **API**: Gitee API v5
- **认证**: Gitee 私人令牌 (Personal Access Token)

## 项目结构

```
gitee-mcp/
├── mcp_core.py         # MCP 核心逻辑（传输无关）
├── server.py           # MCP HTTP 服务器
├── stdio_server.py     # MCP stdio 服务器
├── gitee-mcp-cli       # 命令行工具
├── requirements.txt    # Python 依赖
├── .env               # 环境变量配置 (不纳入 Git)
├── venv/              # Python 虚拟环境 (不纳入 Git)
├── mcp-server.log     # 服务日志
└── README.md          # 项目说明
```

## 快速开始

### 1. 克隆仓库

```bash
git clone https://gitee.com/codelint/gitee-mcp.git
cd gitee-mcp
```

### 2. 创建虚拟环境

```bash
python3 -m venv venv
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境变量

创建 `.env` 文件，配置 Gitee 授权信息：

```env
GITEE_TOKEN=your_gitee_personal_access_token
GITEE_EMAIL=your_email@example.com
```

获取 Gitee 私人令牌：
1. 登录 Gitee 账号
2. 进入「设置」→「私人令牌」
3. 生成新令牌，勾选 `issues` 和 `user_info` 权限

### 5. 启动服务

**必须在虚拟环境中启动服务：**

```bash
# 激活虚拟环境（每次启动前都需要执行）
source venv/bin/activate
```

#### HTTP 模式（传统方式）

```bash
# 默认端口 8000
python3 gitee-mcp-cli serve

# 指定端口
python3 gitee-mcp-cli serve --port=8002
```

服务启动后，将监听 `http://0.0.0.0:8002/mcp`

#### stdio 模式（推荐，Trae IDE 原生支持）

```bash
python3 gitee-mcp-cli stdio
```

在此模式下，Trae IDE 通过 stdin/stdout 与 MCP Server 通信，无需手动启动 HTTP 服务。

**注意**：
- 每次启动服务前都需要先激活虚拟环境 `source venv/bin/activate`
- 如果虚拟环境未激活，会因缺少依赖而启动失败

## 命令行工具

**注意：以下命令都需要在虚拟环境中执行**

```bash
# 激活虚拟环境
source venv/bin/activate

# 查看帮助和命令列表
python3 gitee-mcp-cli

# 启动服务帮助
python3 gitee-mcp-cli serve --help

# 输出 Trae stdio 配置
python3 gitee-mcp-cli trae:stdio

# 输出 Trae HTTP 配置
python3 gitee-mcp-cli trae:http
```

## MCP 工具列表

服务提供以下 MCP 工具：

| 工具名 | 说明 | 必需参数 |
|--------|------|----------|
| `list_issues` | 列出仓库 Issues | owner, repo |
| `get_issue` | 获取单个 Issue 详情 | owner, repo, number |
| `create_issue` | 创建 Issue | owner, repo, title |
| `update_issue` | 更新 Issue | owner, repo, number |
| `list_issue_comments` | 列出 Issue 评论 | owner, repo, number |
| `create_issue_comment` | 创建 Issue 评论 | owner, repo, number, body |
| `get_user_emails` | 获取用户邮箱 | 无 |
| `get_user_info` | 获取当前用户信息（ID、名称、邮箱等） | 无 |

## Trae IDE 配置

### stdio 模式（推荐）

在 Trae IDE 中配置 MCP 服务器：

```json
{
  "mcpServers": {
    "gitee-mcp": {
      "command": "<venv>/bin/python3",
      "args": ["<project>/gitee-mcp-cli", "stdio"],
      "env": {
        "GITEE_TOKEN": "your_gitee_personal_access_token",
        "GITEE_EMAIL": "your_email@example.com"
      }
    }
  }
}
```

**配置说明**：
- `<venv>/bin/python3`：虚拟环境中的 Python 解释器路径（如 `venv/bin/python3`）
- `<project>/gitee-mcp-cli`：`gitee-mcp-cli` 文件的绝对路径
- **必须使用虚拟环境的 Python**，否则 Trae 启动的进程会找不到 `requests` 等依赖

**配置步骤**：
1. 确认虚拟环境已创建并安装了依赖（见上方"安装依赖"步骤）
2. 打开 Trae IDE 设置
3. 找到 MCP 配置选项
4. 添加上述 JSON 配置（将 `<venv>` 和 `<project>` 替换为实际路径）
5. 保存后 Trae 将自动启动并连接 MCP 服务器

### HTTP 模式（传统方式）

```json
{
  "mcpServers": {
    "gitee-mcp": {
      "url": "http://localhost:8002/mcp",
      "headers": {}
    }
  }
}
```

配置步骤：
1. 先手动启动 HTTP 服务：`python3 gitee-mcp-cli serve --port=8002`
2. 打开 Trae IDE 设置
3. 找到 MCP 配置选项
4. 添加上述 JSON 配置
5. 保存后 Trae 将自动连接 MCP 服务器

## API 测试

**注意：测试前请确保服务已在虚拟环境中启动**

```bash
source venv/bin/activate
python3 gitee-mcp-cli serve --port=8002
```

使用 curl 测试 MCP 接口：

### 初始化连接

```bash
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test",
        "version": "1.0"
      }
    }
  }'
```

### 获取工具列表

```bash
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

### 调用工具 (示例：列出 Issues)

```bash
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_issues",
      "arguments": {
        "owner": "codelint",
        "repo": "gitee-mcp",
        "state": "open"
      }
    }
  }'
```

### 创建 Issue

```bash
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "create_issue",
      "arguments": {
        "owner": "codelint",
        "repo": "gitee-mcp",
        "title": "测试 Issue",
        "body": "这是一个测试 Issue"
      }
    }
  }'
```

## 日志查看

服务日志保存在 `mcp-server.log`：

```bash
tail -f mcp-server.log
```

## 协议说明

本服务实现 **MCP HTTP 传输**协议：

- **端点**: `POST /mcp`
- **格式**: JSON-RPC 2.0
- **方法**:
  - `initialize` - 初始化连接
  - `initialized` - 连接确认通知
  - `tools/list` - 获取工具列表
  - `tools/call` - 调用工具
  - `shutdown` - 关闭连接

## 开发说明

### 添加新工具

在 `server.py` 中的 `TOOLS` 列表添加工具定义，并在 `_call_tool` 方法中实现工具逻辑。

### 依赖管理

```bash
# 导出依赖
pip freeze > requirements.txt
```

## 许可证

MIT License