Groki Bot MCP
A gateway for a desktop robot on M5Stack CoreS3: voice, a wake word and an MCP server through which an agent makes it speak
- 212 ★ on the repository
- Last commit
Extended access
Why this level
- Microphone audio from the robot goes to an external voice service, Gemini Live or Grok, and without the wake word model all of it is forwarded
- Optional voice tools, including Mac control and `ask_claude`, give a voice access to the computer and are enabled by separate settings
Install
- Works in
Manual install
git clone https://github.com/JosssphZhou/groki-bot.git && cd groki-bot/gateway && uv sync --all-extrasInstalls the gateway from the repository, then `cp .env.example .env` and edit `.env`. The robot must first be flashed through the web flasher in Chrome or Edge.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Microphone audio from the robot goes to an external voice service, Gemini Live or Grok, and without the wake word model all of it is forwarded
- Optional voice tools, including Mac control and `ask_claude`, give a voice access to the computer and are enabled by separate settings
This is third-party code. Review the repository files before installing.
What it does
Groki Bot is a desktop robot built on M5Stack CoreS3 with a Stack-chan base, with firmware, a computer-side gateway and a hand-off to Grok Bot agents in one repository. For an agent the gateway matters: a small Python service called `stackchan-mcp` that runs on your computer and gives the robot a voice brain. The gateway holds a voice conversation through Gemini Live by default or through Grok login voice, and detects the "Hi Grok" wake word locally, so audio goes to the selected voice service only after you call the robot. On a Mac with a camera the robot turns its head to follow your face. As an MCP server the gateway gives Claude Code, Claude Desktop and other clients the `speak` and `get_status` tools: an agent can make the robot say a text and read its status. Optionally, voice control of the Mac, a voice tool `ask_claude` that hands hard questions to the Claude CLI, and task hand-off to agents in the Grok Bot app can be enabled.
Who it is for. Owners of an M5Stack CoreS3 Stack-chan robot who want voice conversation and the ability to have the robot speak an agent's answers.
Good fit when
- The robot is built and you want it to listen for the wake word and answer by voice through Gemini Live
- An agent finished a long task and the result should be spoken through the robot with `speak`
- You want head tracking of your face and the Mac camera, with the main work on the computer next to the robot
- Hard questions should go by voice through the robot to the Claude CLI, and tasks to a Grok Bot agent
Not a fit when
- There is no robot: the gateway is useless without an M5Stack CoreS3 board with a Stack-chan base
- You need head movement, LED and camera tools over MCP: with this firmware `move_head`, `set_led` and `take_photo` return an error
- The computer and the robot are on different networks: they need a shared Wi-Fi or LAN
- Windows only: the README reports testing on Apple Silicon, Linux should work for voice, and Mac control is macOS only
Example request
When you finish the database migration, say through the robot that everything is done and how many tables changed.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
GEMINI_API_KEYrequired, secret- Google AI Studio key for the Gemini Live voice mode, which is the default. Not needed for Grok login voice.
STACKCHAN_TOKENsecret- A random device secret, for example from `openssl rand -hex 16`. Recommended; an empty value is acceptable only on a trusted network.
STACKCHAN_VOICE_BACKEND- Voice backend: Gemini by default, the value `gbot` enables Grok login voice.
Limitations
With the stock Groki Bot firmware only `speak` and `get_status` work over MCP: it announces `features.mcp=false`, so `move_head`, `set_led`, `set_avatar` and `take_photo` return an error. You need the robot, a shared network, `uv`, Git and the Opus library, plus a Google AI Studio key for Gemini Live.
Grok login voice relies on internal interfaces of the Grok Bot app version 0.71.2 and may break after an update. The firmware is licensed BSL-1.0 and the gateway MIT.
How to disable. Run `claude mcp remove groki` and stop the gateway: if it runs as a service, remove the launchd job or systemd unit. The robot's XiaoZhi server address can be restored on the Bluetooth settings page.
FAQ
How do I connect the Groki Bot gateway to Claude Code?
From the `gateway` directory run `claude mcp add groki -- uv run --all-extras --directory "$(pwd)" stackchan-mcp`. The gateway runs while Claude Code is open. For Claude Desktop, add a block with the `uv` command and the absolute path to `gateway` in `claude_desktop_config.json`.
Which MCP tools work with this firmware?
`speak` to voice a text and `get_status` for the robot state. Other tools such as `move_head`, `set_led`, `set_avatar` and `take_photo` return an error with it and work only with firmware that implements XiaoZhi device tools.
Is a key needed?
The default voice mode needs a `GEMINI_API_KEY` from Google AI Studio. Grok login voice uses the Grok Bot app on the same Mac and needs no separate xAI key. Setting `STACKCHAN_TOKEN` to a random value is recommended.
What is sent to the cloud?
After the wake word, microphone audio goes to the selected voice service, Gemini Live or Grok. Without the wake word model, everything the microphone hears goes to the service while the robot is connected. Camera frames stay on the Mac and are not saved.
How is Groki Bot different from mcp-server-for-xiaozhi?
mcp-server-for-xiaozhi passes Home Assistant tools to the Xiaozhi voice agent. Groki Bot brings its own gateway with voice, a wake word and face tracking for one specific robot, and Claude gets the `speak` and `get_status` commands over MCP.
Discussion
No questions or reviews yet.
Related
MCP serversConnects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
CLI connects Claude Code and Cursor events to a desk robot's movements, screen expressions and end-of-task bell
quackd connects robots to Claude Code and Claude Desktop over MCP: nine tools and an executor with an allowlist
SwitchBot smart-home CLI for devices and scenes, with a built-in MCP server for Claude Code, Codex and Gemini CLI.
A Home Assistant integration that puts GigaChat, YandexGPT or another LLM behind your smart-home voice assistant
An MCP server in a single Go binary: more than 75 local tools for files, shell, browser, calendar and scheduled tasks
README in short
The README briefly introduces the robot and five features: native voice on macOS, a wake word, face tracking, fifteen eye expressions and one-click flashing from Chrome or Edge with over-the-air updates. The quick start takes four steps, followed by a list of docs: hardware, build, architecture and troubleshooting.