Groqcloud MCP Server

🚀 Groq MCP 服务器

这是一个功能完备且智能的 模型上下文协议 (MCP) 服务器，旨在将您的应用程序与强大的 Groq API 集成，为您提供对世界上最快的人工智能模型的优化访问。

它就像一座智能桥梁，允许兼容的客户端（如 Claude Desktop）使用 Groq 的各种模型进行文本补全、音频转录、视觉分析和批量处理。

✨ 主要特性

🧠 支持的模型

该服务器配置为管理并将请求路由到多种 Groq 模型，包括：

• 文本补全 (LLMs)：
  • llama-3.1-8b-instant
  • llama-3.3-70b-versatile
  • deepseek-r1-distill-llama-70b
  • qwen/qwen3-32b（以及用于数学计算的 qwen-qwq-32b）
  • compound-beta、compound-beta-mini
  • allam-2-7b、gemma2-9b-it、llama3-70b-8192、llama3-8b-8192
  • mistral-saba-24b
• 安全防护 (提示/内容防护)：
  • meta-llama/llama-guard-4-12b
  • meta-llama/llama-prompt-guard-2-22m、meta-llama/llama-prompt-guard-2-86m
• 视觉 (多模态)：
  • meta-llama/llama-4-maverick-17b-128e-instruct
  • meta-llama/llama-4-scout-17b-16e-instruct
• 音频 (语音转文本)：
  • whisper-large-v3、whisper-large-v3-turbo
  • distil-whisper-large-v3-en
• 文本转语音：
  • playai-tts、playai-tts-arabic

⚡ 高级功能

• 智能路由 (ModelRouter)： 根据优先级（速度、质量、成本、推理能力、数学计算能力、多语言支持）、提示复杂度和特定功能（视觉、音频）动态选择最佳模型。
• 可控速率限制： 为每个模型智能管理可配置的请求速率和每分钟令牌限制（RPM/TPM），优化 API 使用效率。
• 优化缓存： 内存缓存系统，可配置 TTL（生存时间），用于存储大语言模型的响应，减少延迟和对 API 的冗余调用。
• 详细指标： 全面收集使用指标、性能指标（延迟、吞吐量）、错误信息和模型分布情况，便于分析和监控。
• 强大的错误处理： 集中式错误处理系统，具备自动重试机制，提高 API 请求的弹性。
• 批量处理： 支持 Groq 的批量处理工具，可高效发送大量请求并节省成本。
• 结构化日志和调试： 使用 Winston 实现专业的日志系统，生成结构化日志，并在开发过程中将彩色输出定向到 stderr，便于调试和监控。

📦 安装指南

先决条件

• Node.js：版本 v20.17.0 或更高版本，或 v22.9.0 或更高版本。建议使用 NVM（或适用于 Windows 的 nvm-windows）来管理 Node.js 版本。
• npm：Node.js 包管理器（通常随 Node.js 一起安装，且与推荐版本兼容）。
• TypeScript：版本 5 或更高版本。
• Groq API 密钥：用于对 Groq API 请求进行身份验证。您可以在 https://console.groq.com/keys 获取。

快速安装

1. 克隆仓库：

   git clone [https://github.com/AyrtonFelipe/GroqCloud-MCP_server.git]
   cd groq-mcp-server
   

2. 安装项目依赖：

   npm install
   # 同时安装将 Zod 模式转换为 JSON 模式的库
   npm install zod-to-json-schema
   

3. 配置环境变量： 在项目根目录创建一个 .env 文件（如果不存在，可从 .env.example 复制，前提是有提供）：

   cp .env.example .env
   

   编辑 .env 文件，添加您的 Groq API 密钥：

   GROQ_API_KEY="您的 Groq API 密钥"
   

   （可选：根据需要配置其他变量，如 LOG_LEVEL。）

4. 更新 src/config/models.json： 该文件定义了服务器将使用和公开的 Groq 模型。

   • 移除 不再可用或不想使用的模型条目（请查阅 Groq 控制台的最新列表）。
   • 添加 “支持的模型” 列表中尚未存在的所有模型。对于每个新模型，您必须 填写其所有属性（名称、描述、功能、costPer1kTokens、rateLimits 等），可参考 Groq 官方文档 获取准确值。
   • 调整 models.json 中的 modelSelectionRules 和 complexityThresholds 部分，以反映您拥有的模型和所需的选择逻辑（例如，针对 reasoning、mathematical、multilingual 优先级）。

5. 更新 src/config/constants.ts：

   • 将常量 RATE_LIMITS 与 models.json 中的模型同步。确保 models.json 中的每个模型在 RATE_LIMITS 中都有对应的条目，包含准确的 rpm（每分钟请求数）和 tpm（每分钟令牌数）（请查阅 Groq 文档获取最新值）。
   • 同时更新工具文件（src/tools/*.ts）中的 z.enum，以包含您希望向客户端公开的新模型。

6. 编译项目：

   npm run build
   

7. 启动服务器：

   npm start
   

   服务器将启动并通过 stdin/stdout 等待连接。

💻 使用示例

与 Claude Desktop 配合使用

当您的 MCP 服务器在本地运行后，Claude Desktop 应该能够发现并使用其工具：

1. 启动 Claude Desktop。
2. 检查工具： Groq 工具（groq_text_completion、groq_audio_transcription、groq_vision_analysis、groq_batch_processing）应在 Claude Desktop 界面中显示为已启用（通常在工具菜单或集成菜单中）。
3. 开始交互： 开始与 Claude 对话，并要求它使用这些工具。例如：
   • 使用 groq_text_completion 生成一篇关于 Groq 人工智能能力的文本。
   • 使用 groq_text_completion 工具分析财务数据 { 数据: [100, 250, 80, 400] }，并使用模型：llama-3.3-70b-versatile
   • groq_audio_transcription: 使用 'whisper-large-v3-turbo' 转录文件 '路径/到/您的/音频.mp3'。
   • groq_vision_analysis: 使用 'meta-llama/llama-4-scout-17b-16e-instruct' 描述图片 'https://example.com/您的图片.jpg'。

📚 详细文档

项目结构

.
├── src/
│   ├── config/
│   │   ├── constants.ts         # 系统常量 (RATE_LIMITS, API_ENDPOINTS 等)
│   │   └── models.json          # Groq 模型的详细定义
│   ├── tools/
│   │   ├── audio-transcription.ts # 音频转录工具
│   │   ├── batch-processing.ts    # 批量处理工具
│   │   ├── model-router.ts        # 模型选择的核心逻辑
│   │   ├── text-completion.ts     # 文本补全工具
│   │   └── vision-analysis.ts     # 视觉分析工具
│   │   └── ... (如果实现了其他工具，如文本转语音)
│   ├── types/
│   │   └── groq-types.ts          # Groq 模型的 TypeScript 类型定义
│   ├── utils/
│   │   ├── cache-manager.ts       # 缓存管理器
│   │   ├── error-handler.ts       # 集中式错误处理和重试机制
│   │   ├── logger.ts              # 使用 Winston 配置日志记录
│   │   ├── metrics-tracker.ts     # 收集使用和性能指标
│   │   └── rate-limiter.ts        # 速率限制实现
│   └── server.ts                  # MCP 服务器的主要入口点
├── dist/                          # TypeScript 编译输出
├── logs/                          # 应用程序日志
├── .env                           # 环境变量 (如 GROQ_API_KEY)
├── .gitignore                     # Git 忽略的文件和文件夹
├── package.json                   # 项目元数据和依赖项
├── tsconfig.json                  # TypeScript 编译器配置
└── README.md                      # 本文件

🔧 技术细节

未来规划 (扩展到 Web)

本项目目前配置为使用 StdioServerTransport 进行本地使用。要扩展到 Web 服务器环境（例如生产环境），以下考虑因素至关重要：

• 通信传输： 从 StdioServerTransport 迁移到 Web 传输方式，如 服务器发送事件 (SSE) 或 WebSockets，以便与 Web 客户端进行通信。
• 启动机制： 调整服务器的生命周期，以适应 Web 框架（如 Express、Fastify），使其能够监听 HTTP/HTTPS 端口。
• 协议实现： 实现 HTTP 路由，映射到 MCP 的 JSON-RPC 调用。
• 安全措施： 添加身份验证（如 JWT）、授权、HTTPS 和 CORS 配置，以保护服务器。
• 可扩展性： 实施策略以处理多个客户端和高流量（例如负载均衡、Node.js 集群、使用分布式缓存如 Redis 用于 CacheManager 和 RateLimiter）。

开发者：Ayrton Felipe