# gitingest-mcp
> [!tip]
> **MCP HTTP 服务器**，封装 [gitingest](https://github.com/coderamp-labs/gitingest)，让 Claude Code 能够分析 GitHub 仓库并生成 Obsidian 中文学习笔记。
## ✨ 功能特性
- **GitHub 仓库分析** - 通过 MCP 协议获取仓库摘要和完整内容
- **智能文件过滤** - 默认分析文档文件（md, json, toml, yaml 等）
- **256k Token 自动降级** - 超过限制时自动切换到 README-only 模式
- **私有仓库支持** - 通过 GitHub token 访问私有仓库
- **子目录分析** - 支持分析仓库的特定子目录
- **Obsidian 集成** - 自动调用 Obsidian 相关 skill 生成结构化学习笔记
## 📦 快速开始
### 1. 部署服务器
#### Docker Compose 部署（推荐）
```bash
# 克隆项目
git clone https://github.com/tunanet/gitingest-mcp.git
cd gitingest-mcp
# 启动服务
docker-compose up -d
# 查看日志
docker-compose logs -f
```
#### Docker 部署
```bash
# 构建镜像
docker build -t gitingest-mcp .
# 运行容器
docker run -d \
--name gitingest-mcp \
-p 8000:8000 \
-e GITHUB_TOKEN=your_token_if_needed \
--restart unless-stopped \
gitingest-mcp
```
#### 其他部署方式
<details>
<summary>Systemd 守护进程</summary>
```bash
# 安装依赖
pip install -e .
# 创建 systemd 服务
sudo nano /etc/systemd/system/gitingest-mcp.service
```
添加内容：
```ini
[Unit]
Description=Gitingest MCP Server
After=network.target
[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/gitingest-mcp
Environment="PORT=8000"
ExecStart=/usr/bin/python -m server.main
Restart=always
[Install]
WantedBy=multi-user.target
```
启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable gitingest-mcp
sudo systemctl start gitingest-mcp
```
</details>
<details>
<summary>PaaS 平台部署</summary>
**Railway:**
```bash
npm install -g railway
railway login
railway up
```
**Render:**
1. 在 Render Dashboard 创建新的 Web Service
2. 连接 GitHub 仓库 `tunanet/gitingest-mcp`
3. 设置构建命令: `pip install -e . && uvicorn server.main:app --host 0.0.0.0 --port $PORT`
</details>
### 2. 在 Claude Code 中注册 MCP 服务器
```bash
# 替换为你的部署 URL
claude mcp add --transport http gitingest https://your-app.example.com/mcp
```
### 3. 验证安装
```bash
# 检查 MCP 服务器状态
curl https://your-app.example.com/health
```
## 🚀 在 Claude Code 中使用
### 基本用法
部署完成后，在 Claude Code 中直接与 AI 对话即可：
```
你: 帮我分析 https://github.com/coderamp-labs/gitingest 这个项目，生成 obsidian 中文学习笔记
Claude Code 会：
1. 自动调用 analyze_repo 工具获取仓库分析
2. 理解项目结构和功能
3. 自动调用 Obsidian 相关 skill
4. 生成结构化的 Obsidian 学习笔记
```
### 高级用法
#### 指定子目录
```
分析 https://github.com/owner/repo 的 docs 目录
```
#### 使用全文件模式
```
帮我分析 https://github.com/owner/repo，分析所有源代码文件
```
#### 强制只分析 README
```
分析 https://github.com/owner/repo，只看 README 即可
```
### 工作流程
```mermaid
graph LR
A[用户请求] --> B[Claude Code 调用 MCP]
B --> C[gitingest-mcp 分析仓库]
C --> D[返回分析结果]
D --> E[Claude Code 调用 Obsidian Skill]
E --> F[生成学习笔记]
```
## ⚙️ 配置
### 环境变量
| 变量 | 说明 | 默认值 |
|:-----|:-----|:-------|
| `PORT` | 服务器端口 | `8000` |
| `GITHUB_TOKEN` | GitHub token（私有仓库需要） | - |
### GitHub Token 获取
1. 访问 [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens)
2. 生成新 token（需要 `repo` 权限）
3. 设置环境变量或启动时传入
## 🛠️ MCP 工具参数
`analyze_repo` 工具支持以下参数：
| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:----:|:-----|
| `url` | string | ✅ | GitHub 仓库 URL |
| `subdirectory` | string | ❌ | 只分析指定子目录 |
| `github_token` | string | ❌ | 用于私有仓库的 GitHub token |
| `default_branch` | string | ❌ | 默认分支名（默认为 `main`）|
| `include_patterns` | string | ❌ | 文件包含模式（默认使用文档模式）|
| `fallback_to_readme` | boolean | ❌ | 强制只分析 README |
### include_patterns 选项
| 值 | 说明 |
|:---|:-----|
| 默认（不指定）| 分析文档文件（md, json, toml, yaml, txt, cfg, ini, conf）|
| `"all"` | 分析所有文件（包括源代码）|
| `"*.py,*.js"` | 自定义文件模式 |
## 📝 返回结果格式
```json
{
"summary": {
"repo_name": "owner/repo",
"description": "仓库描述...",
"estimated_tokens": 15000
},
"content": "文件内容...",
"metadata": {
"source_url": "https://github.com/owner/repo",
"include_patterns": "*.md,*.json,...",
"was_fallback": false,
"fallback_reason": null
}
}
```
## 🔒 反向代理配置（生产环境推荐）
服务默认绑定 `127.0.0.1:8000`，建议通过 Nginx 反向代理暴露公网。
### HTTP 配置
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### HTTPS 配置（使用 Let's Encrypt）
```nginx
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## 🧪 本地开发
```bash
# 安装依赖
pip install -e .
# 启动服务器
python -m server.main
# 运行测试
pytest
```
## 📚 使用示例
### 示例 1：分析开源项目
```
你: 帮我分析 https://github.com/tiangolo/fastapi 这个项目，生成 obsidian 中文学习笔记
```
### 示例 2：分析特定子目录
```
你: 分析 https://github.com/owner/repo 的 src/core 目录，生成学习笔记
```
### 示例 3：私有仓库分析
```
你: 分析我公司的私有仓库 https://github.com/mycompany/private-repo
（需提前配置 GITHUB_TOKEN 环境变量）
```
### 示例 4：快速了解项目
```
你: 快速帮我了解 https://github.com/vitejs/vite 这个项目是做什么的
```
## 🐛 故障排除
### MCP 服务器无法连接
1. 检查服务器状态：`curl https://your-app.example.com/health`
2. 检查防火墙设置
3. 确认反向代理配置正确
### 分析超时
- 大型仓库可能需要较长时间
- 默认超时时间为 120 秒
- 可以通过指定 `subdirectory` 减少分析范围
### Token 限制
- 默认使用文档模式以减少 token 使用
- 超过 256k token 会自动降级到 README-only 模式
- 可通过 `fallback_to_readme=true` 强制使用 README 模式
## 📄 License
MIT
## 🙏 致谢
- [gitingest](https://github.com/coderamp-labs/gitingest) - 核心仓库分析库
- [Claude](https://claude.ai) - Anthropic 出品的 AI 助手
