Skip to main content
Glama
BowTiedSwan

grok-oauth-mcp

by BowTiedSwan
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

grok-oauth-mcp

Standalone TypeScript stdio MCP server for xAI Grok using web OAuth PKCE. It is intended for local MCP clients such as Claude Desktop, ChatGPT-compatible MCP hosts, and other stdio MCP launchers.

This server does not require XAI_API_KEY for normal usage. The primary auth path is xAI web OAuth with a local token store.

Requirements

  • Node.js 20+

  • A local MCP client that can launch stdio servers, such as Claude Desktop or another MCP-compatible host.

  • An xAI account with an active SuperGrok subscription or an X Premium+ subscription linked to the X account you sign in with. This matches the Hermes xAI Grok OAuth connector: the browser login works through accounts.x.ai, and xAI links X Premium+ entitlement to the xAI session automatically.

No XAI_API_KEY is used for the normal OAuth path. xAI may still gate OAuth API access by subscription tier; if OAuth succeeds but xAI API calls return 403, your account may not be entitled for that OAuth API surface yet.

Related MCP server: Grok MCP

Features

  • xAI web OAuth PKCE login with the Hermes client ID.

  • Token storage at ~/.config/grok-oauth-mcp/tokens.json by default.

  • Configurable token directory with GROK_OAUTH_MCP_CONFIG_DIR.

  • Refresh-token flow before access token expiry.

  • Configurable xAI API base with XAI_BASE_URL, defaulting to https://api.x.ai/v1.

  • MCP stdio tools for auth, Grok chat, X search, image, video, TTS, and transcription.

  • Multipart upload support for local image/audio paths.

Quick Start

This is the shortest path for a human or agent to get the MCP running, authenticate, and verify that Grok works.

1. Install

From source:

git clone https://github.com/bowtieswan/grok-oauth-mcp.git
cd grok-oauth-mcp
npm install
npm run build

Run directly from the built checkout:

node /absolute/path/to/grok-oauth-mcp/dist/index.js

Or install it globally from the checkout:

npm install -g .
grok-oauth-mcp

Package-runner form:

npx grok-oauth-mcp

2. Add It To Your MCP Client

Use absolute paths when possible. This avoids PATH differences between your shell and GUI apps.

Claude Desktop

Add an MCP server entry that points at your local build or global executable. Local build example:

{
  "mcpServers": {
    "grok-oauth": {
      "command": "node",
      "args": ["/absolute/path/to/grok-oauth-mcp/dist/index.js"]
    }
  }
}

If you installed globally and know the executable path:

{
  "mcpServers": {
    "grok-oauth": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/grok-oauth-mcp"]
    }
  }
}

OpenCode

Add a local MCP server entry under the top-level mcp object in your OpenCode config, usually ~/.config/opencode/opencode.json:

{
  "mcp": {
    "grok-oauth": {
      "command": [
        "/absolute/path/to/node",
        "/absolute/path/to/grok-oauth-mcp"
      ],
      "enabled": true,
      "type": "local"
    }
  }
}

Then restart the MCP client or reload MCP servers. In OpenCode, verify discovery with:

opencode mcp list

You should see grok-oauth connected.

3. Authenticate

Use the MCP tool auth_login with wait=false first. This is the safest mode for most MCP clients because the tool returns the URL immediately.

Input:

{
  "wait": false,
  "timeout_ms": 600000
}

The result contains:

  • auth_url: open this in your browser.

  • state: the OAuth state for this attempt.

  • redirect_uri: normally http://127.0.0.1:56121/callback.

  • token_path: where tokens will be written after success.

Open auth_url, sign in to xAI, then complete one of these two paths.

Path A: Browser Redirects To Localhost

If the browser redirects to http://127.0.0.1:56121/callback?... and shows a success message, login is complete. Run auth_status to confirm.

Path B: xAI Shows A Grok Build Code

Sometimes xAI shows a page saying:

Enter this code to finish signing in
Copy the code below into Grok Build to finish signing in

If that happens, copy the code and call auth_exchange_code immediately:

{
  "code": "paste-the-grok-build-code-here"
}

The code is tied to the most recent auth_login attempt and the saved PKCE verifier. If it expires or you started another login attempt, run auth_login again and use the fresh code from the fresh URL.

If you have a full callback URL instead of a bare code, pass it as callback_url:

{
  "callback_url": "http://127.0.0.1:56121/callback?code=...&state=..."
}

4. Verify Auth

Run auth_status. A successful login returns authenticated: true, has_refresh_token: true, and an expiry time. Token values are never returned.

Tokens are stored at:

~/.config/grok-oauth-mcp/tokens.json

Temporary pending OAuth state is stored at:

~/.config/grok-oauth-mcp/pending_oauth.json

Both files are written with mode 0600 where the local filesystem supports POSIX permissions.

5. Test Grok

After auth_status is authenticated, try a small call. For X search:

{
  "query": "latest xAI Grok updates",
  "filters": {
    "max_results": 5
  }
}

If the first broad search times out, retry with a narrower query and fewer results.

OAuth Details

  • Discovery: https://auth.x.ai/.well-known/openid-configuration

  • Displayed authorization server: accounts.x.ai

  • Client ID: b1a00492-073a-47ea-816f-4c329264a828

  • Scope: openid profile email offline_access grok-cli:access api:access

  • Redirect URI: http://127.0.0.1:56121/callback

  • Authorize URL includes plan=generic and referrer=hermes-agent.

Authentication Notes For Agents

  • Prefer auth_login with wait=false. Do not use wait=true unless your MCP host surfaces stderr or tool output while the call is still running.

  • Always open the exact auth_url from the latest auth_login result.

  • If the page shows a Grok Build code, call auth_exchange_code with that code. Do not try to open /callback manually.

  • If auth_exchange_code returns No pending OAuth login found or Pending OAuth login is expired, run auth_login again and use the fresh URL/code.

  • If xAI returns invalid_grant, the code is stale, already used, or from a different login attempt. Run auth_login again.

Tools

auth_login

Starts OAuth login and returns an authorization URL.

Input:

{
  "wait": false,
  "timeout_ms": 300000
}

Set wait=true only for clients that can show stderr or otherwise surface the URL while the tool is still running.

auth_exchange_code

Exchanges a pasted xAI/Grok Build OAuth code, or a full callback URL, using pending PKCE state from the last auth_login call.

Input with a bare Grok Build code:

{
  "code": "paste-the-grok-build-code-here"
}

Input with a callback URL:

{
  "callback_url": "http://127.0.0.1:56121/callback?code=...&state=..."
}

auth_status

Reports whether a token is stored, whether a refresh token exists, and approximate expiry. Token values are never returned.

auth_logout

Deletes the local token file and any pending OAuth state.

grok_chat

Posts to /responses with store=false. Default model: grok-build-0.1.

Example:

{
  "input": "Explain what this MCP server can do."
}

x_search

Posts to /responses with tools: [{ "type": "x_search" }] and optional filters.

Example:

{
  "query": "latest xAI Grok updates",
  "filters": {
    "max_results": 5
  }
}

grok_tts

Posts to /tts.

Example:

{
  "text": "Hello from Grok.",
  "voice_id": "eve",
  "language": "en"
}

grok_image

Posts to /images/generations for text-to-image and /images/edits when image_path is present.

Defaults:

  • Generation model: grok-imagine-image

  • Edit model: grok-imagine-image-quality

Common image options include aspect_ratio, resolution, size, n, and response_format. Pass values supported by the current xAI/Hermes image surface, such as common aspect ratios like 1:1, 16:9, 9:16, 4:3, and 3:4 when available on your account.

grok_video

Posts to /videos/generations. Supports text-to-video and image-to-video when image_path is present.

Defaults:

  • Text-to-video model: grok-imagine-video

  • Image-to-video model: grok-imagine-video-1.5-preview

Set poll=true to poll /videos/{request_id} until the request leaves a queued or processing state.

grok_transcribe

Posts a local audio file to /stt with multipart form data, matching xAI Grok STT.

Example:

{
  "file_path": "/path/to/audio.wav",
  "language": "en"
}

Troubleshooting

  • Not authenticated. Run auth_login first.: Run auth_login with wait=false, open the returned auth_url, then complete the redirect or use auth_exchange_code with the Grok Build code.

  • Browser cannot reach callback: If xAI showed a Grok Build code, do not manually open /callback; call auth_exchange_code with the code instead. If you expected a redirect, make sure nothing else is using port 56121, then run auth_login again.

  • No pending OAuth login found or Pending OAuth login is expired: Run auth_login again and use the fresh URL/code.

  • invalid_grant: The pasted code is stale, already used, or belongs to a different login attempt. Run auth_login again and paste the fresh code.

  • 403 from xAI: Your xAI account may not have the required SuperGrok or X Premium+ entitlement for the requested Grok API surface.

  • Token refresh fails: Run auth_logout, then auth_login again.

  • Custom API gateway or mock server: Set XAI_BASE_URL to the replacement base URL.

  • Custom token location: Set GROK_OAUTH_MCP_CONFIG_DIR to a directory path. The server writes tokens.json inside it.

Development

npm test
npm run build

Tests mock all OAuth and xAI network calls. They must not call real xAI OAuth or xAI APIs.

License

MIT

Available Tools

9 tools
auth_loginA

Start xAI web OAuth PKCE login using the Hermes Agent client. Use wait=true to capture the localhost callback and store tokens.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoWait for http://127.0.0.1:56121/callback and exchange the authorization code.
timeout_msNoCallback wait timeout in milliseconds. Defaults to 120000.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must fully disclose behavior. It mentions capturing callback and storing tokens but omits details like potential user interaction, browser opening, or side effects (e.g., invalidating existing sessions). The timeout parameter hints at waiting, but the description lacks comprehensive behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded purpose. Every sentence adds value without redundancy. No unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the tool's action but does not mention return values or output. Given no output schema and no annotations, the description should cover what the agent can expect after invocation (e.g., tokens or status). This gap reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters described. The description adds context for 'wait' (capture callback) and 'timeout_ms' (callback wait timeout) but does not significantly extend beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Start'), the resource ('xAI web OAuth PKCE login'), and specifies the client ('Hermes Agent client'). It distinguishes itself from sibling tools like auth_logout and auth_status by focusing on login initiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises 'Use wait=true to capture the localhost callback and store tokens,' providing clear usage context. However, it does not explicitly mention when not to use this tool or provide alternatives beyond the sibling context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

auth_logoutB

Delete the local OAuth token store.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the destructive action of deleting the token store, which is the core behavior. However, it lacks details on side effects (e.g., server-side session invalidation) or response, and there are no annotations to supplement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that directly states the action. It is appropriately sized and front-loaded, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, parameterless tool, the description is adequate but minimal. It doesn't explain return values (none) or potential errors, but the simplicity makes it acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema coverage, the description doesn't need to add parameter meaning. It correctly conveys the tool's purpose without redundant info, meeting the baseline requirement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Delete the local OAuth token store' uses a specific verb and resource, clearly indicating the action. It distinguishes from siblings like auth_login and auth_status, implying logout functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives (e.g., auth_login or auth_status). The usage is implied as logging out, but no context or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

auth_statusA

Show local xAI OAuth token status without revealing token values.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It states the tool does not reveal token values, but lacks details on side effects, idempotency, or authentication requirements. Adequate for a simple read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Front-loaded with purpose and behavioral constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, and the description does not describe the return format. For a simple status tool, some output description would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. The description adds no parameter info, which is appropriate given zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows local xAI OAuth token status, distinguishing it from login/logout siblings. The phrase 'without revealing token values' adds specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking token status, no authentication needed? The context is clear but does not explicitly exclude other tools or provide when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_chatC

Send a Grok chat or responses request to /responses with store=false. Defaults to model grok-build-0.1.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputNo
messagesNo
promptNo
modelNo

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It mentions store=false and default model but lacks disclosure on auth, rate limits, error handling, or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, technically concise, but the inclusion of store=false is important. Could be front-loaded with more essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters, no output schema, and no annotations, the description is insufficient. It does not explain parameter roles, return values, or usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only the model parameter gets a default value explanation. The other three parameters (input, messages, prompt) are not described, despite schema having 0% description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it sends a Grok chat/responses request and mentions the API endpoint and default model, distinguishing it from other grok tools like grok_image. However, 'chat or responses request' is slightly ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings or alternatives. No prerequisites, exclusions, or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_imageC

Generate or edit images through /images/generations or /images/edits. Defaults to grok-imagine-image and grok-imagine-image-quality.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptNo
image_pathNo
mask_pathNo
modelNo
aspect_ratioNo
resolutionNo
sizeNo
nNo
response_formatNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must fully disclose behavior. It mentions defaults but fails to describe rate limits, authentication needs, side effects, or responses. For a tool with both generation and editing capabilities, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (two sentences) and front-loaded, which is efficient. However, it sacrifices essential detail, making it under-specified for a tool with many parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters with 0% coverage, no output schema, and minimal behavioral info, the description is wholly inadequate. An AI agent would struggle to use this tool correctly without external knowledge.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the description must explain parameters. It only notes default model parameters but does not clarify any of the 9 properties, leaving their semantics entirely to the schema, which lacks descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates or edits images and mentions the API endpoints, providing a specific verb-resource pair. It distinguishes from sibling tools like grok_video.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use generation vs. editing, nor any mention of alternatives or prerequisites. The description is too brief to offer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_transcribeC

Transcribe a local audio file through /audio/transcriptions using multipart form upload.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes
modelNo
languageNo
promptNo
response_formatNo
temperatureNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It does not disclose file size limits, supported audio formats, authorization requirements, or whether the operation is read-only or destructive. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is concise and front-loaded, but it lacks necessary detail. While not verbose, it is under-specified for a tool with multiple parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, no output schema, and no annotations, the description is incomplete. It does not explain parameter usage, return values, or any constraints, making it insufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It does not explain any of the 6 parameters (file_path, model, language, prompt, response_format, temperature). The description adds no value beyond the basic function.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (transcribe), the resource (local audio file), and the method (multipart form upload). It distinguishes from sibling tools like auth, chat, image, TTS, video, and search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The description is purely functional without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_ttsD

Generate speech through /tts.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputNo
textNo
voice_idNo
voiceNo
languageNo
output_formatNo
response_formatNo
speedNo
optimize_streaming_latencyNo

TDQS

D1.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description provides no information about side effects, authentication needs, or behavioral traits. Since no annotations exist, the description carries the full burden but only repeats the endpoint path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one sentence) but does not earn its place as it fails to provide necessary details. Conciseness without substance is under-specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters, no schema descriptions, no output schema, no annotations), the description is grossly incomplete. It does not cover required inputs, output format, or any usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 9 parameters and 0% schema description coverage, the description adds no meaning beyond parameter names. It does not explain what 'input', 'text', 'voice', etc. do or how they relate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Generate speech through /tts.', which clearly indicates the tool's function as a text-to-speech generator. It distinguishes from sibling tools like grok_chat or grok_image, but is vague about the specific resource or input format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like grok_transcribe (if that transcribes speech) or other audio-related tools. No when-not or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_videoB

Generate text-to-video or image-to-video through /videos/generations, optionally polling /videos/{request_id}.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptNo
image_pathNo
modelNo
aspect_ratioNo
durationNo
fpsNo
pollNo
poll_interval_msNo
poll_timeout_msNo

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions optional polling, which is a key behavioral trait for async tasks. However, with no annotations, it fails to disclose other behaviors like destructive actions (likely write), auth requirements, or rate limits. The polling detail adds some value but is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (one sentence) and front-loaded with the main action. However, it is too brief for a tool with 9 parameters and no schema descriptions, sacrificing necessary detail for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, no output schema, no annotations), the description is severely incomplete. It does not cover return values, error handling, or parameter formats, making it inadequate for reliable tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and only 9 parameters, the description provides no parameter semantics. It does not explain prompt, image_path, model, aspect_ratio, duration, fps, poll, poll_interval_ms, or poll_timeout_ms, leaving the agent uninformed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates videos from text or images, referencing the specific endpoint /videos/generations. It distinguishes from sibling tools like grok_image (image generation) and grok_chat (text chat) by specifying video output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for video generation but does not explicitly state when to use this tool over others. It lacks guidance on prerequisites, alternative tools for related tasks (e.g., image generation), or conditions for polling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv0.1.0
    • First observedauth_login
    • First observedauth_logout
    • First observedauth_status
    • First observedgrok_chat
    • First observedgrok_image
    • First observedgrok_transcribe
    • First observedgrok_tts
    • First observedgrok_video
    • First observedx_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a distinct operation: authentication (login/logout/status), Grok modalities (chat, image, transcribe, TTS, video), and search. No overlap in functionality.

Naming Consistency4/5

Tools use consistent verb_noun naming with subdomain prefixes (auth_, grok_), but 'x_search' breaks the pattern by not using a prefix consistent with others. Still predictable overall.

Tool Count5/5

With 9 tools, the server covers authentication and main Grok API capabilities without being bloated or sparse. Each tool serves a clear purpose.

Completeness4/5

Covers core auth lifecycle and major Grok features (chat, image, audio, video, search). Missing potential management tools (e.g., model listing) but not necessary for primary use cases.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Grok MCP Server

    BrewMyTech
    A
    license
    B
    quality
    D
    maintenance
    Enables interaction with the Grok AI through an MCP server, supporting chat completions, text completions, embeddings, and model operations with streaming capabilities.
    5
    29
    7
    MIT

  • bluex-mcp

    Derek-Wong213
    A
    license
    A
    quality
    B
    maintenance
    MCP server for live X/Twitter and web search, driven by your locally logged-in Grok CLI and leveraging your X Premium or SuperGrok subscription quota.
    3
    1
    MIT