AI导哈

代码分析服务

一个基于Python的模型上下文协议（MCP）服务器，利用Google的Gemini AI模型的大上下文窗口分析整个代码库，适用于理解项目架构、查找实现和验证大型项目中的功能。

  • by crazyvibecoder42
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 crazyvibecoder42/gemini-mcp

使用说明

Gemini MCP服务器

基于Python的模型上下文协议（MCP）服务器，封装Gemini CLI以提供大型代码库分析功能。该服务器利用谷歌Gemini AI模型的大规模上下文窗口来分析整个代码库，使其成为了解项目架构、查找实现和验证大型项目功能的理想选择。

特性

  • 大上下文窗口：利用Gemini庞大的上下文窗口分析整个代码库
  • 灵活的文件包含：使用 @ 包含文件、目录或整个项目的语法
  • 异步执行：具有超时支持的非阻塞子流程执行
  • 全面的错误处理：通过可操作的故障排除步骤清除错误消息
  • 可配置的：基于环境变量的配置，具有灵活性
  • 生产准备就绪：正确的日志记录、验证和错误处理

先决条件

  • Python 3.11或更高版本
  • Gemini CLI：从安装 谷歌/双子座cli
  • Google API密钥：设置Gemini API访问
  • Claude桌面版：用于使用MCP服务器

安装

使用紫外线（推荐）

# Navigate to project directory
cd /path/to/gemini-mcp

# Install with development dependencies
uv pip install -e ".[dev]"

使用pip

# Navigate to project directory
cd /path/to/gemini-mcp

# Install with development dependencies
pip install -e ".[dev]"

配置

环境变量

创建一个 .env 项目根目录中的文件（可选）：

# Path to Gemini CLI executable (default: "gemini")
GEMINI_CLI_PATH=gemini

# Default timeout in seconds (default: 60)
GEMINI_TIMEOUT=120

# Maximum query length in characters (default: 100000)
MAX_QUERY_LENGTH=100000

# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
LOG_LEVEL=INFO

Claude桌面配置

在Claude Desktop的配置文件中配置MCP服务器：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini-mcp": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/gemini-mcp/src/gemini_mcp_server/server.py"
      ],
      "env": {
        "GEMINI_CLI_PATH": "gemini",
        "GEMINI_TIMEOUT": "120",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

重要：始终使用 绝对路径 对两者 command 和 args.

查找绝对路径

# Find Python path
which python   # or: which python3

# Find project path
cd /path/to/gemini-mcp
pwd
# Output: /Users/username/projects/gemini-mcp

# Server path will be:
# /Users/username/projects/gemini-mcp/src/gemini_mcp_server/server.py

完整配置示例

{
  "mcpServers": {
    "gemini-mcp": {
      "command": "/Users/username/.local/bin/python",
      "args": [
        "/Users/username/projects/gemini-mcp/src/gemini_mcp_server/server.py"
      ],
      "env": {
        "GEMINI_CLI_PATH": "/usr/local/bin/gemini",
        "GEMINI_TIMEOUT": "180",
        "LOG_LEVEL": "DEBUG",
        "MAX_QUERY_LENGTH": "200000"
      }
    }
  }
}

用法

与Claude Desktop一起使用

配置后 answer_query 该工具将在Claude Desktop中提供。

查询句法

服务器支持Gemini CLI @ 文件包含语法：

单文件分析

@src/main.py What does this file do?

多个文件

@package.json @src/index.js Analyze the dependencies used in the code

整个目录

@src/ Summarize the architecture of this codebase

多个目录

@src/ @tests/ Has authentication been implemented?

当前目录

@./ What is this project about?

查询示例

架构概述:

@src/ Provide a high-level overview of the codebase architecture. What are the main components and how do they interact?

特征验证:

@backend/ @middleware/ Is rate limiting implemented for the API? If so, show me the relevant code.

相关性分析:

@package.json @yarn.lock @src/ Analyze all dependencies used in this project. Are there any security concerns or outdated packages?

实施搜索:

@src/ @lib/ Has dark mode been implemented in this codebase? Show all relevant files.

代码审查:

@src/auth/ Review the authentication implementation. Are there any security issues or best practices violations?

自定义超时

对于大型查询，请指定自定义超时时间：

Query: "@./ Analyze the entire codebase structure"
Timeout: 300

测试

运行测试

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=gemini_mcp_server --cov-report=html

# Run specific test file
pytest tests/test_server.py -v

# Run specific test
pytest tests/test_server.py::test_execute_gemini_cli_success -v

手动测试

直接测试服务器：

# Start the server
python src/gemini_mcp_server/server.py

# You should see logs in stderr:
# 2025-10-27 10:00:00 - gemini_mcp_server.server - INFO - Starting Gemini MCP Server
# 2025-10-27 10:00:00 - gemini_mcp_server.server - INFO - Transport: stdio

# Press Ctrl+C to stop

直接测试Gemini CLI：

# Basic query
gemini -p "@README.md Summarize this file"

# Directory query
gemini -p "@src/ What are the main components?"

# Multiple files
gemini -p "@package.json @src/index.js Analyze dependencies"

故障排除

服务器未出现在Claude Desktop中

检查：

  1. 配置文件路径正确
  2. JSON有效（使用 python -m json.tool < config.json)
  3. Python路径是绝对正确的(which python)
  4. Server.py路径是绝对正确的
  5. 配置更改后重新启动Claude Desktop

调试：

# Validate JSON
python -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Test Python path
/absolute/path/to/python --version

# Test server starts
/absolute/path/to/python /absolute/path/to/server.py

工具调用失败

检查日志：

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-gemini-mcp.log

# Filter for errors
tail -f ~/Library/Logs/Claude/mcp-server-gemini-mcp.log | grep ERROR

常见问题：

  1. 未找到Gemini CLI：确保Gemini CLI位于PATH中或已设置 GEMINI_CLI_PATH
  2. 权限错误：检查文件/目录权限
  3. 超时错误：增加 GEMINI_TIMEOUT 对于大型查询
  4. 文件未找到：路径在 @ 语法与Claude Desktop的工作目录有关

超时错误

解决：

  1. 增加配置中的超时时间：

    "env": {
  "GEMINI_TIMEOUT": "300"
}

  2. 使用较小的查询或更具体的文件模式

  3. 在查询中传递自定义超时参数

路径解析错误

问题: @src/main.py 未找到

原因：路径是相对于Claude Desktop运行的位置，而不是服务器位置。

解决方案：使用绝对路径或确保Claude Desktop从您的项目目录运行。

建筑

组件

  • FastMCP服务器：处理MCP协议和工具注册
  • 异步子进程层：执行带超时处理的Gemini CLI
  • 错误处理程序：分类并提供用户友好的错误消息
  • 日志记录：全面的调试/信息/错误日志记录到stderr

通信流

Claude Desktop
     ↓ JSON-RPC over stdio
FastMCP Server (server.py)
     ↓ async subprocess
Gemini CLI
     ↓ API call
Google Gemini API

关键设计决策

  1. 没有stdout写入：所有日志记录都会转到stderr，以避免损坏JSON-RPC
  2. 异步优先：对于非阻塞执行，所有操作都是异步的
  3. 超时处理：通过适当的清理防止挂起大型查询
  4. 错误分类：提供具体的、可操作的错误消息
  5. 基于环境的配置：通过环境变量灵活配置

发展

项目结构

gemini-mcp/
├── src/
│   └── gemini_mcp_server/
│       ├── __init__.py
│       └── server.py          # Core MCP server implementation
├── tests/
│   ├── __init__.py
│   └── test_server.py         # Comprehensive test suite
├── project-documentation/     # Detailed documentation
│   ├── CLAUDE.md
│   ├── implementation-guide.md
│   ├── mcp-server-architecture.md
│   ├── error-handling-strategy.md
│   ├── testing-strategy.md
│   └── deployment-configuration.md
├── pyproject.toml            # Project configuration
├── .gitignore
└── README.md

添加功能

  1. 遵循FastMCP模式（装饰器、异步函数、类型提示）
  2. 在stderr中添加全面的DEBUG/INFO/ERROR日志记录
  3. 使用pytest-asyncio编写快乐路径测试
  4. 更新文档
  5. 切勿使用 print() -仅记录到stderr

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 确保所有测试通过： pytest -v
  5. 提交拉取请求

许可证

此项目按原样提供，用于Claude Desktop和模型上下文协议。

资源

  • MCP文件: https://modelcontextprotocol.io
  • FastMCP: https://github.com/jlowin/fastmcp
  • Gemini CLI: https://github.com/google/gemini-cli
  • Claude桌面版: https://claude.ai/desktop

支持

对于问题、疑问或功能请求：

  1. 检查上面的故障排除部分
  2. 查阅文档 project-documentation/
  3. 检查服务器日志以获取详细的错误信息
  4. 验证Gemini CLI是否独立工作

备注：此服务器需要使用有效的Google API密钥安装和配置Gemini CLI。该服务器充当Claude Desktop和Gemini CLI之间的桥梁，通过MCP实现大型代码库分析。

相关 MCP