Groq 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 e qwen-qwq-32b （数学） - compound-beta, compound-beta-mini - allam-2-7b, gemma2-9b-it, llama3-70b-8192, llama3-8b-8192 - mistral-saba-24b

• 内容保护（Prompt/Content Guard）：

- 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

• Áudio（语音转文本）：

- whisper-large-v3, whisper-large-v3-turbo - distil-whisper-large-v3-en

• 文本转语音（Text-to-Speech）：

- playai-tts, playai-tts-arabic

⚡ 高级资源

• Roteamento Inteligente（模型路由器）根据优先级（速度，质量，成本，推理，数学，多语言），提示符的复杂性和特定功能（视觉，音频）动态选择理想模型。
• 速率限制控制a对每个模型可配置的请求限制和每分钟令牌 （RPM/TPM） 进行智能管理，从而优化 API 使用。
• 缓存优化内存缓存系统具有可配置的 TTL （Time-To-Live） 响应，可减少延迟和冗余的 API 调用。
• 详细指标全面收集利用率、性能（延迟、吞吐量）、错误和模型分布，用于分析和监控。
• 强大的错误处理集中式错误处理系统，可自动重试 API 请求，提高弹性。
• 批处理支持 Groq 批量加工工具，以节省成本高效发送大量请求。
• 结构化日志和调试专业的Winston日志系统，生成结构化日志并将彩色输出定向到 stderr 开发中，促进调试和监控。

🛠️ 安装

先决条件

• npmNode.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

1. 安装工程依赖关系 ：

   npm install
   # Instale também a biblioteca para conversão de schemas Zod para JSON Schema
   npm install zod-to-json-schema

1. 设置环境变量 ：

创建文件 .env 在项目的根（如果不存在，你可以复制 .env.example 如果提供：

   cp .env.example .env

编辑文件 .env 使用您的 Groq API 密钥：

   GROQ_API_KEY="sua_chave_api_groq_aqui"

*（可选：设置其他变量如 LOG_LEVEL 如有必要）。*

1. 临时化 src/config/models.json:

此文件定义了您的服务器将使用和显示的 Groq 模板 。

- 雷莫瓦 不再可用或不想使用的模板条目（请在 Groq 控制台中查看最新的列表）。 - 添加 “支持模型”列表（上面）中尚未出现的所有模型。对于每个新模型，你必须 填写您的所有属性 （名称，描述，能力， costPer1kTokens, rateLimits等）领事 Groq 官方文件 以获得准确的值。 - 调整章节 modelSelectionRules e complexityThresholds 电子显微镜 models.json 以反映您拥有的模型和所需的选择逻辑（例如： reasoning, mathematical, multilingual).

1. 临时化 src/config/constants.ts:

- 将一名警察定罪 RATE_LIMITS 与您的模型 models.json确保每个模型在 models.json 有一个相应的条目在 RATE_LIMITS com rpm （每分钟请求数）e tpm 精确（每分钟令牌）（请参阅 Groq 文档了解最新值）。 - 也更新 z.enum 工具文件（src/tools/*.ts）包括您想要向客户展示的新模型。

1. 编译工程 ：

   npm run build

1. 启动服务器 ：

   npm start

您的服务器将处于活动状态，正在等待通过 stdin/stdout.

🤝 使用 Claude Desktop

一旦您的MCP服务器在本地运行，Claude Desktop应该能够检测到它并使用其工具：

1. 如克劳德桌面。
2. 检查工具： Groq 工具groq_text_completion, groq_audio_transcription, groq_vision_analysis, groq_batch_processing必须在 Claude Desktop 界面（通常在工具菜单或集成）中启用。
3. 内部： 开始和Claude谈谈，让他使用这些工具。例如：

- Use groq_text_completion para gerar um texto sobre as capacidades do Groq para IA. - Com a ferramenta groq_text_completion, analise os dados financeiros { dados: [100, 250, 80, 400] } e use o modelo: llama-3.3-70b-versatile - groq_audio_transcription: transcreva o arquivo 'caminho/para/seu/audio.mp3' usando 'whisper-large-v3-turbo'. - groq_vision_analysis: descreva a imagem em 'https://example.com/sua-imagem.jpg' usando 'meta-llama/llama-4-scout-17b-16e-instruct'.

📊 项目结构

.
├── src/
│   ├── config/
│   │   ├── constants.ts         \# Constantes do sistema (RATE\_LIMITS, API\_ENDPOINTS, etc.)
│   │   └── models.json          \# Definições detalhadas dos modelos Groq
│   ├── tools/
│   │   ├── audio-transcription.ts \# Ferramenta para transcrição de áudio
│   │   ├── batch-processing.ts    \# Ferramenta para processamento em lote
│   │   ├── model-router.ts        \# Lógica central para seleção de modelos
│   │   ├── text-completion.ts     \# Ferramenta para completação de texto
│   │   └── vision-analysis.ts     \# Ferramenta para análise de visão
│   │   └── ... (novas ferramentas como Text-to-Speech, se implementadas)
│   ├── types/
│   │   └── groq-types.ts          \# Definições de tipos TypeScript para modelos Groq
│   ├── utils/
│   │   ├── cache-manager.ts       \# Gerenciador de cache
│   │   ├── error-handler.ts       \# Tratamento centralizado de erros e retries
│   │   ├── logger.ts              \# Configuração de logging com Winston
│   │   ├── metrics-tracker.ts     \# Coleta de métricas de uso e desempenho
│   │   └── rate-limiter.ts        \# Implementação de rate limiting
│   └── server.ts                  \# Ponto de entrada principal do servidor MCP
├── dist/                          \# Saída da compilação TypeScript
├── logs/                          \# Logs da aplicação
├── .env                           \# Variáveis de ambiente (ex: GROQ\_API\_KEY)
├── .gitignore                     \# Arquivos e pastas a serem ignorados pelo Git
├── package.json                   \# Metadados e dependências do projeto
├── tsconfig.json                  \# Configurações do compilador TypeScript
└── README.md                      \# Este arquivo

📈 Próximos Passos (Escalabilidade para Web)

Este projeto está configurado para uso local com StdioServerTransport. Para escalar para um ambiente de servidor web (e.g., produção), as seguintes considerações seriam cruciais:

• Transporte de Comunicação: Migrar de StdioServerTransport para um transporte web como Server-Sent Events (SSE) ou WebSockets para comunicação com clientes web.
• Mecanismo de Start: Adaptar o ciclo de vida do servidor para um framework web (e.g., Express, Fastify) que escuta em portas HTTP/HTTPS.
• Protocolagem: Implementar rotas HTTP que mapeiam para chamadas JSON-RPC do MCP.
• Segurança: Adicionar autenticação (e.g., JWT), autorização, HTTPS, e configuração de CORS para proteger o servidor.
• Escalabilidade: Implementar estratégias para lidar com múltiplos clientes e alto tráfego (e.g., load balancing, clusters Node.js, caches distribuídos como Redis para CacheManager e RateLimiter).

Desenvolvido por Ayrton Felipe.