MCP Server Semgrep

MCP Server Semgrep

由以下项目提供支持：

关于项目

本项目最初受到 Semgrep tool、The Replit Team 及其 Agent V2 的健壮性启发，也参考了 stefanskiasan/semgrep-mcp-server 的实现；此后经过重大架构调整，使安装和维护更加简便。

MCP Server Semgrep 是一个符合 Model Context Protocol 规范的服务，可将强大的 Semgrep 静态分析工具与 Anthropic Claude 等 AI 助手集成。它能够通过对话界面直接进行高级代码分析、检测安全漏洞并提升代码质量。

集成优势

面向开发者和开发团队：

• 全面的源代码分析 - 检测整个项目中的问题，而不仅限于单个文件
• 主动错误检测 - 在潜在问题演变为严重缺陷之前将其识别出来
• 持续提升代码质量 - 定期扫描和重构，逐步改进代码库
• 风格一致性 - 识别并修复代码中的不一致之处，例如：
  • CSS 中任意设置的 z-index 层级
  • 命名规范不一致
  • 代码重复
  • 使用“魔法数字”而非命名常量

面向安全：

• 自动验证代码中的已知漏洞 - 扫描已知安全问题模式
• 自定义安全规则 - 创建项目专属规则
• 团队教育 - 通过检测潜在问题，教授安全编程实践

面向项目维护和开发：

• “实时”文档 - AI 可以解释代码片段存在问题的原因以及如何修复
• 减少技术债务 - 系统地检测并修复有问题的部分
• 改进代码审查 - 自动检测常见问题，让团队能够专注于更复杂的问题

主要功能

• 直接集成官方 MCP SDK
• 简化架构，整合处理器
• 简洁的 ES Modules 实现
• 高效的错误处理和路径验证，确保安全
• 提供英语和波兰语界面及文档
• 全面的单元测试
• 完善的文档
• 跨平台兼容（Windows、macOS、Linux）
• 灵活检测和管理 Semgrep 安装

功能

Semgrep MCP 服务提供以下工具：

• scan_directory：扫描源代码以查找潜在问题
• list_rules：显示 Semgrep 支持的可用规则和语言
• analyze_results：详细分析扫描结果
• create_rule：创建自定义 Semgrep 规则
• filter_results：按各种条件筛选结果
• export_results：以各种格式导出结果
• compare_results：比较两组结果（例如，修改前后）

常见用例

• 部署前进行代码安全分析
• 检测常见编程错误
• 在团队内落实编码标准
• 重构并改进现有代码质量
• 识别风格和代码结构中的不一致之处（例如，CSS、组件组织）
• 教育开发者了解最佳实践
• 验证修复是否正确（比较修改前后的扫描结果）

安装

前置条件

• Node.js v18+
• TypeScript（用于开发）

选项 1：从 Smithery.ai 安装（推荐）

通过 Smithery.ai 安装和使用 MCP Server Semgrep 是最简单的方式：

1. 访问 Smithery.ai 上的 MCP Server Semgrep
2. 按照安装说明将其添加到兼容 MCP 的客户端
3. 配置 Semgrep API 令牌和允许的工作区根目录等可选设置

这是 Claude Desktop 和其他 MCP 客户端的推荐方法，因为它会自动处理所有依赖项和配置。

选项 2：从 NPM Registry 安装

# Using npm
npm install -g mcp-server-semgrep

# Using pnpm
pnpm add -g mcp-server-semgrep

# Using yarn
yarn global add mcp-server-semgrep

此软件包也可从其他注册表获取：

• MCP.so

选项 3：从 GitHub 安装

# Using npm
npm install -g git+https://github.com/vetcoders/mcp-server-semgrep.git

# Using pnpm
pnpm add -g git+https://github.com/vetcoders/mcp-server-semgrep.git

# Using yarn
yarn global add git+https://github.com/vetcoders/mcp-server-semgrep.git

选项 4：本地开发环境设置

1. 克隆仓库：

git clone https://github.com/vetcoders/mcp-server-semgrep.git
cd mcp-server-semgrep

2. 安装依赖项（支持所有主流软件包管理器）：

# Using pnpm (recommended)
pnpm install

# Using npm
npm install

# Using yarn
yarn install

3. 构建项目：

# Using pnpm
pnpm run build

# Using npm
npm run build

# Using yarn
yarn build

注意：安装过程会自动检查 Semgrep 是否可用。如果未找到 Semgrep，你会收到安装说明。

工作区根目录约定

此服务只会读取和写入明确允许的工作区根目录中的文件。

• 默认情况下，允许的根目录是进程的工作目录（process.cwd()）。
• 对于 Claude Desktop、Smithery 或任何不会在项目根目录内启动服务的启动器，请将 MCP_SERVER_SEMGREP_ALLOWED_ROOTS 设置为一个或多个绝对目录。
• 多个根目录请使用所在平台的路径分隔符：macOS/Linux 上为 :，Windows 上为 ;。

身份验证模式

此服务不会自行处理 Semgrep 账户，而是调用已安装的 semgrep CLI，并依赖 Semgrep 的常规身份验证行为。

• 本地终端和本地开发运行通常可以使用当前 OS 账户现有的 semgrep login 会话。
• Claude Desktop、Smithery、容器或 CI 等托管启动方式应优先使用明确设置的 SEMGREP_APP_TOKEN，以确保行为一致。
• 如果需要在不同计算机或运行器之间移植配置，SEMGREP_APP_TOKEN 仍是最安全的选择。

Semgrep 安装选项

Semgrep 可通过多种方式安装：

• 通过软件包管理器：

  # Using pnpm
  pnpm add -g semgrep
  
  # Using npm
  npm install -g semgrep
  
  # Using yarn
  yarn global add semgrep
  

• Python pip：

  pip install semgrep
  

• Homebrew（macOS）：

  brew install semgrep
  

• Linux：

  sudo apt-get install semgrep
  # or
  curl -sSL https://install.semgrep.dev | sh
  

• Windows：

  pip install semgrep
  

与 Claude Desktop 集成

将 MCP Server Semgrep 与 Claude Desktop 集成有两种方式：

方法 1：通过 Smithery.ai 安装（推荐）

1. 访问 Smithery.ai 上的 MCP Server Semgrep
2. 点击“Install in Claude Desktop”
3. 按照屏幕上的说明操作

方法 2：手动配置

1. 安装 Claude Desktop
2. 更新 Claude Desktop 配置文件（claude_desktop_config.json），并将以下内容添加到 servers 部分。

对于在已通过 semgrep login 进行身份验证的用户账户下启动的本地进程，Semgrep CLI 可能可以复用该登录状态。对于由桌面端管理或共享的环境，我们仍建议明确设置 SEMGREP_APP_TOKEN：

{
  "mcpServers": {
    "semgrep": {
      "command": "node",
      "args": [
        "/your_path/mcp-server-semgrep/build/index.js"
      ],
      "env": {
        "SEMGREP_APP_TOKEN": "your_semgrep_app_token",
        "MCP_SERVER_SEMGREP_ALLOWED_ROOTS": "/Users/you/projects"
      }
    }
  }
}

3. 启动 Claude Desktop，然后开始询问代码分析相关问题。

如果要扫描多个工作区，请将 MCP_SERVER_SEMGREP_ALLOWED_ROOTS 设置为由平台分隔符分隔的绝对路径列表。

使用示例

扫描项目

Could you scan my source code in the /projects/my-application directory for potential security issues? That directory is already included in MCP_SERVER_SEMGREP_ALLOWED_ROOTS.

样式一致性分析

Analyze the z-index values in the project's CSS files and identify inconsistencies and potential layer conflicts.

创建自定义规则

Create a Semgrep rule that detects improper use of input sanitization functions.

筛选结果

Show me only scan results related to SQL injection vulnerabilities.

识别有问题的模式

Find all "magic numbers" in the code and suggest replacing them with named constants.

创建自定义规则

你可以根据项目的特定需求创建自定义规则。以下是一些可创建的规则示例：

检测不一致的 z-index 的规则：

rules:
  - id: inconsistent-z-index
    pattern: z-index: $Z
    message: "Z-index $Z may not comply with the project's layering system"
    languages: [css, scss]
    severity: WARNING

检测已弃用导入的规则：

rules:
  - id: deprecated-import
    pattern: import $X from 'old-library'
    message: "You're using a deprecated library. Consider using 'new-library'"
    languages: [javascript, typescript]
    severity: WARNING

开发

测试

pnpm test

项目结构

├── src/
│   └── index.ts          # Main entry point and all handler implementations
├── scripts/
│   └── check-semgrep.js  # Semgrep detection and installation helper
├── build/                # Compiled JavaScript (after build)
└── tests/                # Unit tests

更多文档

有关如何使用该工具的详细信息，请参阅：

• USAGE.md - 详细的使用说明
• README_PL.md - 波兰语文档
• examples/ - 有趣且实用的 Semgrep 规则示例——“代码恐怖殿堂”

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

开发者

vetcoders

🤖 在 Claude Code 和 MCP Tools 的帮助下开发

致谢

• 感谢 stefanskiasan 提供最初的灵感
• 感谢 Anthropic 提供 Claude 和 MCP 协议
• 感谢 Semgrep 提供优秀的静态分析工具