One Grok teammate. Every coding agent.

Install UniGrok Core once, connect every MCP-capable IDE, and use @grok from any project. Start with a no-key local model, a Grok Build login, an optional xAI API key, or any combination of those routes.

http://localhost:4765/mcp

This clone, the commands below, and the service they start on port 4765 are the complete public offering. Private provider coordination and operator infrastructure are not part of UniGrok Core.

Get running in three minutes

You need Docker Desktop and Git. Choose at least one inference route:

1. No-key local model — Docker Model Runner plus a compatible local model.
2. Grok Build login — subscription or available free-tier CLI access.
3. xAI developer API key (console.x.ai) — optional and metered; adds provider-hosted files, media, search, and code execution.

UniGrok discovers the routes that are actually ready. A local-only installation stays local and reports unsupported cloud-only capabilities honestly.

In a hurry? npx @djtelicloud/unigrok prints these setup steps in your terminal. (A full launcher that runs the setup for you is planned; today UniGrok installs via Docker, below.)

1. Download and build

git clone https://github.com/djtelicloud/grok-mcp-server.git
cd grok-mcp-server
docker compose build

2. Choose an inference route

No paid key or CLI login. Enable Docker Model Runner, pull a pinned Gemma model, and start it locally:

docker desktop enable model-runner
docker model pull ai/gemma3:4B-Q4_K_M
docker model run --detach ai/gemma3:4B-Q4_K_M

This route uses Docker Desktop's private container endpoint and no API key. Leave host-side TCP support disabled: Docker Model Runner's API is unauthenticated, and enabling --tcp can expose it beyond localhost on some installations. The pinned model supplies bounded local text assistance; UniGrok does not pretend that it provides cloud search, media generation, or a separately certified code role.

Grok Build. Log in once — the device login runs inside the container and stores the session in a private Docker volume:

docker compose run --rm grok-cli-auth

Want the Grok CLI on your own machine too? It is optional:

curl -fsSL https://x.ai/cli/install.sh | bash

xAI API key (optional, metered). Adds provider-hosted files, vision, image/video, search, code execution, and bounded recovery. Keep the key in the service environment only — never in IDE MCP JSON:

export XAI_API_KEY='<your key>'

Any one route works alone. Configure more than one if you want bounded, receipted recovery between compatible routes.

3. Start UniGrok

docker compose up -d grok-mcp
curl --fail --silent http://127.0.0.1:4765/readyz

You are ready when the response says "status":"ready". On Windows PowerShell, prefer curl.exe -fsS http://127.0.0.1:4765/readyz if the curl alias is unreliable.

Multi-step agentic work (Ground pack)

UniGrok’s agent tool is leaf labor. Your IDE or automation remains the orchestrator.

For multi-step work, put a short Mission Brief in task (goal, options, constraints, done-when, return shape). Retry at most a few times with the same goal and an appended finding if a try fails. Prefer densified returns: WHAT / WHY / DELTA / NEXT.

Offline / free local path: when subscription or API is unavailable, Core can still use a staged local model route (Docker Model Runner or loopback OpenAI-compatible runtime). See Local model routes. Relay resolved_plane and cost receipts; disable web/X tools for true offline briefs; fail closed for cloud-only media.

Day-1 is this clone plus http://localhost:4765/mcp. No GitHub token and no hosted MCP URL are required. grok_mcp_onboard_client is optional IDE help (consent first). Contributors who want the Ground pack after GitHub auth can follow CONTRIBUTING.md. Day-1 is Core + Ground pack only (not a second labor Docker seat, not extra operator nodes). Heavier capacity is a separate maintainer grant when someone runs an approved extra node under their map.

Official GitHub contributors (optional)

UniGrok can detect whether the authenticated caller is one of your official GitHub contributors. This never trusts X-Client-ID alone.

Service environment (examples):

# Fast path: explicit allowlist of GitHub logins
export UNIGROK_GITHUB_CONTRIBUTOR_ALLOWLIST='djtelicloud,curtisfratianne'

# And/or live GitHub API checks (service token — never put a user PAT in IDE MCP JSON)
export UNIGROK_GITHUB_TOKEN='ghp_…'   # or GITHUB_TOKEN
export UNIGROK_GITHUB_CONTRIBUTOR_REPOS='djtelicloud/grok-mcp-server,your-org/your-other-repo'
export UNIGROK_GITHUB_CONTRIBUTOR_ORGS='your-org'

# Local single-operator bind (optional)
export UNIGROK_GITHUB_LOGIN='djtelicloud'

grok_mcp_status and grok_mcp_discover_self return an affiliation object: is_official_contributor (true/false/null), source, and whether a login was detected. Use this for soft UX (contributor tips, onboard tone) — not as a secret vault.

Optional local bearer protection is available for /mcp and /v1:

export UNIGROK_LOCAL_MCP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose up -d --force-recreate grok-mcp
printf '%s\n' "$UNIGROK_LOCAL_MCP_TOKEN"

Store that bearer in the IDE's secret-backed MCP header configuration. A SHA-256 digest can be supplied as UNIGROK_LOCAL_MCP_TOKEN_SHA256 instead of retaining plaintext in the service environment. Health and readiness endpoints remain unauthenticated.

New to Grok-powered coding? Cursor (referral link) is an easy on-ramp — set up a Grok plane above whenever