Grok Gadgets gateway
On this page
A local MCP server that lets MCP clients today, and your Grok Bot later, list and control gadgets: a built-in simulated light, Linux gadgets and ESP32 devices. Experimental alpha: Grok Bot and hardware are not verified yet (project status). Independent project, not affiliated with SpaceXAI or xAI.
Quick start
Needs Git and uv.
git clone https://github.com/adidshaft/grok-gadgets-gateway.git
cd grok-gadgets-gateway
uv sync --locked
uv run grok-gadgets-gateway init
uv run grok-gadgets-gateway serve --simulator
init prints pasteable MCP client settings. Then call the tools from MCP Inspector:
first success in five minutes.
How it works
The gateway gives any MCP client six tools:
| Tool | What it does |
|---|---|
gadgets_list_devices |
Lists gadgets, their commands and what each one does. Call it first. |
gadgets_get_state |
Reads a gadget's last reported state and how fresh it is. |
gadgets_command |
Sends a command and waits up to 3 seconds for the result. |
gadgets_command_status |
Reads the result of a slower command later. |
gadgets_read_events |
Reads button presses and other events in order. |
gadgets_diagnostics |
A support report with no tokens, state or arguments. |
A result is the gadget's own report, not proof of a physical effect.
Connect a gadget
init prints two settings blocks with absolute paths: one where your MCP client starts the
gateway (stdio), and one for a running serve (http://127.0.0.1:8766/mcp with the bearer
token from ~/.config/grok-gadgets/mcp-token). init --client http prints just one.
Gadgets connect to 127.0.0.1:8765 with their own token:
uv run grok-gadgets-gateway enroll desk-lamp --token-file desk-lamp.token
enroll desk-lamp --rotate issues a new token for the same gadget. Write gadgets with the
Linux SDK or the
ESP32 SDK; the Linux SDK's dev
command needs no token at all. Both ports are loopback only.
Grok Bot today
A cloud Grok Bot cannot open 127.0.0.1 on your computer, so today the gateway works with
local MCP clients. A supported remote route is later work
(HARD-GROK-REMOTE-001). serve is not an
OAuth server, and a tunnel does not replace the bearer token. Never expose port 8765. Read
remote access and security first.
Troubleshooting
| Symptom | Next step |
|---|---|
| Not sure which command | Run grok-gadgets-gateway --help. Use serve for a long-running process; stdio is for an MCP client that starts the gateway itself. |
| No simulated light | Start with --simulator. |
401 from the client |
Send Authorization: Bearer <token> with the exact contents of the token file. |
| Config rejected | Use strict v1 JSON within the documented bounds. |
Command still accepted or dispatched |
The gadget is slow. Poll gadgets_command_status; never resend with a new command ID. |
Learn more
- First success with MCP Inspector and the simulator guide
- Local operation, architecture and protocol 0.1.0
- Demo without HTTP:
uv run python -m grok_gadgets_gateway.demo(uses test-only controls) - Shared docs and the website: hub repository and https://grok-gadgets.pages.dev/
Community
Questions, build photos and ideas are welcome on
r/GrokGadgets. Report bugs and request features in
GitHub Issues. New here? Pick a
good first issue
and read CONTRIBUTING. Get help: SUPPORT.
Contribute on the dev branch; main holds tagged stable releases (branches).
License and affiliation
Apache-2.0; see LICENSE and NOTICE. Grok Gadgets is an independent open-source project. It is not affiliated with, endorsed by or sponsored by SpaceXAI or xAI, which make Grok and Grok Bot. Pre-publication commit dates were reconstructed; see the history record.