Development Tools

How to run Grok Build locally after it is open source: Tutorial on connecting to MCP, Skills and Plugins

This article introduces how the open source Grok Build can be installed locally on Windows, macOS, and Linux, and is connected to MCP, Skills, Plugins, and compatible Claude Code extensions.

Grok Build is xAI’s open source terminal AI programming agent. It runs with a full-screen TUI and grok CLI, which can understand the code base, edit files, execute commands, search the web, and can also access scripts or CI in headless mode. After it is open source, you can not only view the implementation of its agent runtime, tool calling and extension system, but also directly access MCP, Skills and Plugins on your local machine using the official release version.

This article focuses on “install the official binary first, and then access the extensions one by one”. Source code build is suitable for people who want to study or modify Grok Build itself; there is no need for ordinary users to compile the Rust project from the beginning.

Quick Answer

The shortest path is: install grok, enter the project directory and run grok to complete the login, and then execute grok inspect to view the configuration, Skills, Plugins and MCP servers it has discovered. Then use grok mcp add to add a read-only, directory-scoped MCP service for verification.

Grok Build will recognize .grok/ in the project and is also compatible with Claude Code’s Skills, Plugins, MCP, Hooks, CLAUDE.md and .claude/rules/. Therefore, when you already have a Claude Code workspace, you usually check the automatic discovery results first, and do not rush to copy a configuration.

What does Grok Build open source?

The repository released by xAI contains the Rust source code and agent runtime of grok CLI/TUI. The public content covers components such as agent loop, terminal and file tools, workspace operations, configuration, MCP, Markdown and sandbox; the official description also clearly lists Skills, Plugins, Hooks, MCP servers and subagents extension system.

This does not mean “everyone should run from source”. The official also provides pre-compiled installation methods for macOS, Linux and Windows. Source code construction requires dependencies such as Rust, DotSlash and protoc, and the Windows source code construction is officially marked as best-effort and has not been tested in this source tree. For daily development, priority is given to installing the release version, and the source code is only built when troubleshooting implementation or contributing patches.

Install and start a local session

Windows PowerShell 

1
2

irm https://x.ai/cli/install.ps1 | iex
grok --version

macOS, Linux or Git Bash 

1
2

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

After entering your warehouse, start:

1
2

cd your-project
grok

First launch usually opens a browser for authentication. In environments where the browser cannot be opened, API Key can be set:

1
2

export XAI_API_KEY="xai-..."
grok

The corresponding writing method for Windows PowerShell is:

1
2

$env:XAI_API_KEY = "xai-..."
grok

Do not write keys into repositories, screenshots, or AGENTS.md. If long-term configuration is required, use system environment variables or your password management tool instead of submitting to Git.

First use grok inspect to see the automatic discovery results

Before adding any extensions, run:

1

grok inspect

It displays the loaded configuration sources, directive files, Skills, Plugins, Hooks and MCP servers in the current directory. This step is important because Grok Build will look up the project root directory and also read the configuration in the user directory; the project-level MCP configuration with the same name will also overwrite the user-level configuration.

If the project already uses Claude Code, Grok will automatically read Claude’s marketplaces, plugins, skills, MCPs, agents, hooks and CLAUDE.md, .claude/rules/. Confirm the result of grok inspect first, and then decide whether to create a new .grok/ directory. This can avoid the same service being loaded repeatedly or the permissions being accidentally enlarged.

Accessing the MCP: Start with a restricted local directory

The MCP server will expose external tools to Grok, and the tool names have the <server>__<tool> namespace. The simplest way to add it is grok mcp add.

The following example only gives a specified directory to the filesystem MCP server; replace /path/to/dir with the actual directory, and do not directly authorize the entire user directory or disk root directory:

1

grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

Commonly used management commands:

1
2
3

grok mcp list
grok mcp doctor filesystem
grok mcp remove filesystem

Remote MCPs can be added via HTTP. The OAuth type service will perform browser authorization when it is used for the first time; when using a static token, it should be read from the environment variable instead of writing the token directly into the configuration:

1
2

grok mcp add --transport http linear https://mcp.linear.app/mcp
grok mcp add --transport http api https://mcp.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

When you need to share the MCP declaration with the warehouse, add --scope project, and Grok will write .grok/config.toml in the current directory:

1

grok mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

Project configuration can be submitted, keys should not be submitted. Team members can set API_TOKEN individually, and then let ${API_TOKEN} expand when loading the configuration.

MCP configuration file example

You can also edit the user-level configuration file directly: ~/.grok/config.toml for macOS/Linux or %USERPROFILE%\.grok\config.toml for Windows.

1
2
3
4
5
6
7
8
9

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
startup_timeout_sec = 30
tool_timeout_sec = 6000

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
headers = { "x-mcp-session-id" = "{{session_id}}" }

After configuration, run grok inspect again and check connectivity with grok mcp doctor <名称>. The npx server running for the first time may need to download dependencies; if it times out at startup, increase startup_timeout_sec carefully and do not misjudge the timeout issue as a permission issue.

Skills: put into project or user directory

Skills are reusable folders containing Markdown instructions, scripts, and resources. Grok discovers them from:

  • ./.grok/skills/ in the project, and search up to the warehouse root directory;
  • ~/.grok/skills/ in the user directory;
  • Plugin-enabled skills/ directory;
  • Extra path to [skills] paths for ~/.grok/config.toml.

Project-specific skills can use a similar structure:

1
2
3
4
5
6

.grok/
└── skills/
    └── release-check/
        ├── SKILL.md
        └── scripts/
            └── check.sh

SKILL.md should clearly state trigger conditions, allowed tools, inputs and outputs, and safety boundaries. User-callable Skills will be displayed as /<skill-name> slash commands; automatically triggered Skills should avoid overly broad descriptions to avoid each task being loaded incorrectly.

Plugins: Package and manage multiple extensions

Plugin can package skills, agents, hooks, MCP servers and LSP servers, suitable for teams to share a set of fixed workflows. Grok will discover them from project .grok/plugins/, user ~/.grok/plugins/, the marketplace installation directory, and [plugins] paths for config.toml; the path can also be specified temporarily via --plugin-dir <PATH>.

Entering /plugins, /skills, /hooks or /mcps in TUI will open the same extension management interface. Install or enable the smallest set of extensions first, and then verify them one by one. In particular, do not open all plug-ins that can execute shells, write Git, and access cloud services at the beginning.

If the team already has a marketplace for Claude Code plugins, Grok’s compatibility layer can read them directly. Only create a separate .grok/plugins/ if you need Grok-specific configuration, or want to isolate it from Claude’s configuration.

Local model and headless mode

Grok Build supports adding custom models in user-level config.toml, such as OpenAI-compatible endpoint or local inference service:

1
2
3
4
5
6
7
8

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

This model can be selected after configuration:

1
2

grok inspect
grok -p "Explain this codebase" -m my-model

grok -p is an interface-less mode, suitable for script, CI or other application integration; --output-format streaming-json can be added when machine-readable output is required. When used in CI, create a separate low-privilege token, restrict the working directory, and explicitly disable automated irreversible Git or deployment operations.

Frequently Asked Questions and Security Boundaries

Why doesn’t the extension take effect?

Check in order:

  1. Execute grok inspect in the expected project directory;
  2. Use grok mcp list to confirm whether the server has been registered;
  3. Use grok mcp doctor <名称> to view configuration and network diagnostics;
  4. Check whether the project-level .grok/config.toml covers the user-level server with the same name;
  5. Check whether the environment variable is visible in the same terminal session where grok was started.

Can the configuration of Codex or Claude Code be directly reused?

Most extensions and directive files of Claude Code can be automatically discovered by Grok, but “can be read” does not mean that every third-party extension should be directly trusted. First execute grok inspect in the test warehouse, check the extension source, permissions and startup commands, and then decide whether to use it in real projects.

What should I do if source code compilation fails?

If your goal is just to use Grok Build, it’s often faster to use the official pre-compiled installation package instead. When you really need to compile the source code, prepare Rust, DotSlash and protoc according to the warehouse README, and give priority to building on macOS or Linux hosts that are officially marked as supported. Source builds on Windows should not currently be used as the default path for production environments.

official reference

© 2022 - 2026 KnightLi Blog
记录并分享
Built with Hugo
Theme Stack designed by Jimmy