Groq MCP Server

Query models hosted on Groq for lightning-fast inference directly from Claude and other MCP clients through the Model Context Protocol (MCP).

Use MCP to access vision models for interpreting visual data from images, instantly generate speech from text, process thousands of requests through Groq's batch processing, and even build apps with full access to Groq's documentation.

With the Groq MCP server you can try tasks like:

Agentic Tasks, Code Generation & Web Search

• What is Groq's Compound Beta? Use the compound tool. Summarize with one line then turn into voice
• Please retrieve the current Bitcoin price from CoinGecko API and calculate the value of 0.38474 bitcoins?
• What is the weather in SF right now?
• Generate and run code, which means you can make API calls, get data from webpages, and much more
• This feature uses the new compound-beta agentic tools system

Vision & Understanding

• "Describe this image [URL to image]"
• "Analyze this image and extract key information as JSON [URL to image]"

Speech & Audio

• "Convert this text to speech using the Arista-PlayAI voice: [text]"
• "Read this text aloud in Arabic: [text]"
• "Transcribe this audio file using whisper-large-v3: [url to mp3]"
• "Translate this foreign language audio to English [url to mp3]"

Batch Processing

• "Process the following batch of prompts: [location of a jsonlines file]" (read more here)

Local Tools

• "Run git status in my project folder" — executes shell commands on the local machine via run_shell_command (PowerShell on Windows, bash on macOS/Linux)
• "Read the contents of config.json" — returns a local file's content to the LLM via read_file
• "Save this summary to output.txt" — writes text to a local file path via write_file
• "What Groq chat models do I have access to?" — list_chat_models queries /v1/models live (no hardcoded whitelist)

Quickstart with Claude Desktop

• Get a Groq API key for free at console.groq.com

2. Install uv (Python package manager), install with curl -LsSf https://astral.sh/uv/install.sh | sh or see the uv repo for additional install methods.
3. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

{
  "mcpServers": {
    "groq": {
      "command": "uvx",
      "args": ["groq-mcp"],
      "env": {
        "GROQ_API_KEY": "your_groq_api_key",
        "BASE_OUTPUT_PATH": "/path/to/output/directory"  # Optional: Where to save generated files (default: ~/Desktop)
      }
    }
  }
}

If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu in the top left and select "Enable Developer Mode".

If you want to install the MCP from code, scroll down to "Contributing".

Other MCP Clients

For other clients like Cursor and Windsurf:

1. Install the package:

   # Using UV (recommended)
   uvx install groq-mcp
   
   # Or using pip
   pip install groq-mcp
   

2. Generate configuration:

   # Print config to screen
   groq-mcp-config --api-key=your_groq_api_key --print
   
   # Or save directly to config file (auto-detects location)
   groq-mcp-config --api-key=your_groq_api_key
   
   # Optional: Specify custom output path
   groq-mcp-config --api-key=your_groq_api_key --output-path=/path/to/outputs
   

That's it! Your MCP client can now use these Groq capabilities:

• 🗣️ Text-to-Speech (TTS): Fast, natural-sounding speech synthesis
• 👂 Speech-to-Text (STT): Accurate transcription and translation
• 🖼️ Vision: Advanced image analysis and understanding
• 💬 Chat: Ultra-fast LLM inference with Llama 4 and more (model list fetched live from your account)
• 📦 Batch: Process large workloads efficiently
• 🖥️ Local Shell: Run shell commands on the local machine (PowerShell / bash)
• 📁 File I/O: Read and write local files directly from the LLM

Contributing

If you want to contribute or run from source:

Installation Options

Option 1: Quick Setup (Recommended)

1. Clone the repository:

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

2. Run the setup script to initialize the virtual environment and install all dependencies:

   • On macOS/Linux:

     ./scripts/Linux_setup.sh
     

   • On Windows:

     .\win_setup.bat
     

   (This creates a .venv directory, installs the core and dev dependencies, and configures pre-commit hooks).

3. Run the Claude install script to register the Groq MCP server with Claude Desktop:

   • On macOS/Linux:

     ./scripts/install.sh
     

   • On Windows:

     .\install.bat
     

   (On macOS, this writes to ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, this writes to %APPDATA%\Claude\logs\../claude_desktop_config.json. Make sure to restart or refresh Claude Desktop afterward. The install script also automatically injects the Groq MCP config into the Antigravity CLI mcp.json if present).

4. Copy .env.example to .env and add your Groq API key:

   • On macOS/Linux:

     cp .env.example .env
     

   • On Windows:

     copy .env.example .env
     

   Edit .env and add your API key

Option 2: Manual Setup

1. Clone the repository:

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

2. Create a virtual environment and install dependencies using uv:

   uv venv
   source .venv/bin/activate
   uv pip install -e ".[dev]"
   

3. Copy .env.example to .env and add your Groq API key:

   cp .env.example .env
   # Edit .env and add your API key
   

Available Scripts

The scripts directory contains several utility scripts for different Groq API functionalities:

Vision & Image Analysis

./scripts/groq_vision.sh <image_file> [prompt] [temperature] [max_tokens] [output_directory]
# Example:
./scripts/groq_vision.sh "./input/image.jpg" "What is in this image?"

Text-to-Speech (TTS)

./scripts/groq_tts.sh "Your text" [voice_name] [model] [output_directory]
# Example:
./scripts/groq_tts.sh "Hello, world!" "Arista-PlayAI"

Speech-to-Text (STT)

./scripts/groq_stt.sh <audio_file> [model] [output_directory]

Utility Scripts

• list_groq_voices.sh: Display available TTS voices
• list_groq_stt_models.sh: Show available STT models
• groq_batch.sh: Process batch operations
• groq_translate.sh: Translate text or audio

Development Scripts

# Run tests
./scripts/test.sh
# Run with options
./scripts/test.sh --verbose --fail-fast
# Run integration tests
./scripts/test.sh --integration

# Debug and test locally
mcp install server.py
mcp dev server.py

Troubleshooting

Logs when running with Claude Desktop can be found at:

• Windows: %APPDATA%\Claude\logs\groq-mcp.log
• macOS: ~/Library/Logs/Claude/groq-mcp.log

Acknowledgments

This project is inspired by the ElevenLabs MCP Server. Thanks!