GroqCloud MCP server for AI agents

Groq MCP Server is an intelligent bridge that connects applications with Groq's powerful AI API. It enables compatible clients like Claude Desktop to access Groq's fast AI models for text completion, audio transcription, vision analysis, and batch processing, making it easy to leverage advanced AI capabilities without direct API integration.

Installation Requirements

Prerequisites

Node.js: Version v20.17.0 or higher, or v22.9.0 or higher
npm: Node.js package manager (typically included with Node.js)
TypeScript: Version 5 or higher
Groq API Key: Required for authentication. Get yours at https://console.groq.com/keys

Quick Setup

Clone the repository and navigate to the project folder:

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

Install dependencies:

npm install
npm install zod-to-json-schema

Set up environment variables: Create a .env file in the project root:
```
cp .env.example .env
```
Edit the .env file with your Groq API key:
```
GROQ_API_KEY="your_groq_api_key_here"
```
Update model configuration: Edit the src/config/models.json file to:
- Remove any unavailable models
- Add all supported models with their properties
- Adjust the modelSelectionRules and complexityThresholds sections
Update constants: Modify src/config/constants.ts to:
- Synchronize the RATE_LIMITS constant with your models
- Update the z.enum values in tool files to include your models
Compile the project:
```
npm run build
```
Start the server:
```
npm start
```

Using with Claude Desktop

Once your MCP server is running locally, Claude Desktop should be able to discover and use its tools:

Start Claude Desktop
Verify Tools: The Groq tools (groq_text_completion, groq_audio_transcription, groq_vision_analysis, groq_batch_processing) should appear in Claude Desktop's interface

Interact with the tools. Example commands:

Text completion:

Use groq_text_completion to generate text about Groq's AI capabilities.

Text completion with model specification:

With the groq_text_completion tool, analyze this financial data {data: [100, 250, 80, 400]} using model: llama-3.3-70b-versatile

Audio transcription:

groq_audio_transcription: transcribe the file 'path/to/your/audio.mp3' using 'whisper-large-v3-turbo'.

Vision analysis:

groq_vision_analysis: describe the image at 'https://example.com/your-image.jpg' using 'meta-llama/llama-4-scout-17b-16e-instruct'.

Supported Models

Text Completion (LLMs)

llama-3.1-8b-instant
llama-3.3-70b-versatile
deepseek-r1-distill-llama-70b
qwen/qwen3-32b and qwen-qwq-32b (for mathematics)
compound-beta, compound-beta-mini
allam-2-7b, gemma2-9b-it, llama3-70b-8192, llama3-8b-8192
mistral-saba-24b

Security (Prompt/Content Guard)

meta-llama/llama-guard-4-12b
meta-llama/llama-prompt-guard-2-22m, meta-llama/llama-prompt-guard-2-86m

Vision (Multimodal)

meta-llama/llama-4-maverick-17b-128e-instruct
meta-llama/llama-4-scout-17b-16e-instruct

Audio (Speech-to-Text)

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

Text-to-Speech

playai-tts, playai-tts-arabic

Advanced Features

Intelligent Model Routing: Dynamically selects the ideal model based on priorities
Controlled Rate Limiting: Manages request and token limits per minute
Optimized Caching: In-memory cache system with configurable TTL
Detailed Metrics: Comprehensive collection of usage and performance metrics
Robust Error Handling: Centralized error handling with automatic retry capability
Batch Processing: Support for Groq's batch processing tool
Structured Logging and Debugging: Professional logging system with Winston

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "groqcloud" '{"command":"npm","args":["start"],"env":{"GROQ_API_KEY":"${GROQ_API_KEY}"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "groqcloud": {
            "command": "npm",
            "args": [
                "start"
            ],
            "env": {
                "GROQ_API_KEY": "${GROQ_API_KEY}"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "groqcloud": {
            "command": "npm",
            "args": [
                "start"
            ],
            "env": {
                "GROQ_API_KEY": "${GROQ_API_KEY}"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect