# Grok Mcp Server

> Local-first Grok MCP server & gateway. One shared Grok agent for Cursor, Claude Code, VS Code, Codex & Desktop. xAI API + CLI planes, Control Center.

- **Type:** MCP server
- **Install:** `agentstack add mcp-djtelicloud-grok-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [djtelicloud](https://agentstack.voostack.com/s/djtelicloud)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [djtelicloud](https://github.com/djtelicloud)
- **Source:** https://github.com/djtelicloud/grok-mcp-server
- **Website:** https://grokmcp.org/

## Install

```sh
agentstack add mcp-djtelicloud-grok-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://github.com/djtelicloud/grok-mcp-server/actions)
[](https://github.com/djtelicloud/grok-mcp-server/releases)
[](pyproject.toml)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://docs.x.ai/?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=badge-docs)

# UniGrok · one Grok gateway for every coding agent

> Run Grok once on your machine. Point every IDE agent at it. Keep the xAI
> credential on the server — never in each editor.

UniGrok is a local-first [MCP](https://modelcontextprotocol.io) gateway for
[xAI Grok](https://docs.x.ai/). Cursor, Claude, VS Code, Codex, Antigravity, and
other MCP clients share **one** Streamable HTTP endpoint:

```text
http://localhost:4765/mcp
```

It routes across the **xAI developer API** (metered) and the **SuperGrok CLI
subscription** (when authenticated), and returns the answer under `response`
with route / plane / cost metadata.

Current release: **v0.6.0**.

---

## 1. What you get

- Shared `@grok` / `agent` tool for every IDE on your laptop
- Server-side credentials (API key and/or CLI OAuth)
- Optional local Core UI for status: `http://localhost:4765/ui/`
- A habit you can opt into: critique Implementation Plans with Grok before the
  user sees them

Your other projects do **not** need UniGrok repo folders, contributor trees, or
special mounts.

## 2. Prerequisites

- Git
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
- An MCP-capable IDE
- At least one Grok credential path:
  - **xAI API key** from [console.x.ai](https://console.x.ai/), **or**
  - **SuperGrok / Grok CLI** device login (subscription)

Docker Desktop is the current packaging path for the shared service. Treat it as
how UniGrok runs on your machine — not as “you are a Docker developer.”

## 3. Run the gateway (one path)

> [!WARNING]
> UniGrok is not published on PyPI.
> `pip install mcp-grok` installs an unrelated project; use this GitHub checkout.
> There is no real `npx unigrok` server yet — Docker (or `uv` + compose) **is** the install.

**Fast path (copy/paste):**

```bash
git clone https://github.com/djtelicloud/grok-mcp-server.git && cd grok-mcp-server
uv run python main.py init
docker compose up --build -d
```

`init` creates `.env` if missing and prints IDE MCP snippets for
`http://localhost:4765/mcp`. After the service is healthy, you can **close this
repo** and work in any project with `@grok`.

Before checking readiness, complete **one** credential path:

- **xAI API:** set the developer key in server `.env` before starting Compose
  (or rerun `docker compose up -d` after editing it).
- **CLI subscription:** after the image is up, run:

```bash
docker compose run --rm grok-cli-auth
```

Then verify the usable plane:

```bash
curl --fail -s http://localhost:4765/readyz
```

You are ready when `/readyz` reports `"status":"ready"`. `/healthz` only proves
the process is up; CLI-only installs must authenticate before this readiness
check.

## 4. Connect your IDE (paste this to your agent)

Copy the block for your IDE from the `init` output, or paste this prompt to your
local coding agent:

```text
Configure UniGrok MCP for this machine:
- Streamable HTTP URL: http://localhost:4765/mcp
- Send a stable X-Client-ID header for this IDE (e.g. cursor, claude-code, vscode, codex)
- Never put XAI_API_KEY in IDE MCP settings; credentials stay in UniGrok's server .env
- After connecting, call tools/list and grok_mcp_discover_self
- Prefer the UniGrok agent tool when I say @grok or want a second opinion
- When I ask for a multi-step Implementation Plan, get a UniGrok second opinion
  (agent mode thinking or reasoning) and improve the plan before showing it —
  only if I want that habit; do not silently spend metered API credits
- Do not invent a second MCP port, Forge, or land workflow for ordinary use
```

Detailed multi-IDE notes: [docs/ide-setup.md](docs/ide-setup.md) (public path
only; contributor dual-runtime detail lives in CONTRIBUTING).

## 5. Prove it in 60 seconds

1. Restart the IDE MCP client.
2. Ask: “Call UniGrok discover_self and tell me which credential planes are ready.”
3. Ask for a small plan, then: “Get a UniGrok second opinion on that plan before
   you show me the Implementation Plan.”

Optional status UI (this machine only): open
[http://localhost:4765/ui/](http://localhost:4765/ui/).

## 6. Security (short)

1. Keep `XAI_API_KEY` and CLI OAuth on the UniGrok service — never in IDE configs.
2. API plane is metered; CLI subscription cost is not exposed by the provider —
   UniGrok only tracks local CLI activity.
3. Stable UniGrok does not browse your project unless you pass
   `workspace_context`.
4. Loopback Core UI is for the machine owner; it is not a public multi-user
   console.
5. Do not paste secrets into chat.

## 7. Project site (optional)

The public site at [https://grokmcp.org](https://grokmcp.org) is **bound to the
existing project** repository. It is not an idless installer template. For the
optional contributor control surface, **GitHub App OAuth establishes identity**
and each privileged request performs a **fresh installation-token lookup** of
repo role; a **Sites rollback fallback** remains only for the legacy identity
binding path. That control plane does not replace local UniGrok MCP on
`localhost:4765`, and it never holds your xAI key.

## 8. Where docs live

| You are… | Use |
|---|---|
| Installing / connecting an IDE | This README |
| An agent needing schemas and operations | [OKF knowledge bundle](https://grokmcp.org/docs/okf/index.md) (also via `discover_self` and local `/docs/okf/`) |
| Public “smarter defaults” recipes | [docs/public-intelligence/](docs/public-intelligence/) |
| Changing UniGrok itself | [CONTRIBUTING.md](CONTRIBUTING.md) |

**Source of truth:** this repo’s `docs/okf/` + the site OKF.  
**GitHub Wiki (optional):** human-friendly **mirror only**, generated from OKF
(see [docs/wiki-okf-mirror.md](docs/wiki-okf-mirror.md)). Do not hand-edit the
wiki as product docs. Empty or stale wiki is not an outage — use OKF.

## 9. Next steps

| I want… | Go here |
|---|---|
| More IDE examples | [docs/ide-setup.md](docs/ide-setup.md) |
| Agent knowledge (OKF) | [https://grokmcp.org/docs/okf/index.md](https://grokmcp.org/docs/okf/index.md) |
| Architecture | [architecture.md](architecture.md) |
| Security reporting | [SECURITY.md](SECURITY.md) |
| **Contribute to UniGrok itself** | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Project site | [https://grokmcp.org](https://grokmcp.org) |

Contributors and admins: dual-runtime Forge, landing, Swarm, and insider Console
behavior are documented only in [CONTRIBUTING.md](CONTRIBUTING.md) — not required
for ordinary use.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [djtelicloud](https://github.com/djtelicloud)
- **Source:** [djtelicloud/grok-mcp-server](https://github.com/djtelicloud/grok-mcp-server)
- **License:** MIT
- **Homepage:** https://grokmcp.org/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-djtelicloud-grok-mcp-server
- Seller: https://agentstack.voostack.com/s/djtelicloud
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.