@pkwadsy/grok-mcp 1.0.0

package/README.md

@@ -0,0 +1,87 @@
+# grok-mcp
+
+MCP server that wraps the xAI Grok API. Lets Claude and other AI agents delegate thinking, planning, and real-time search to Grok.
+
+## Setup
+
+```bash
+npm install -g @pkwadsy/grok-mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx @pkwadsy/grok-mcp
+```
+
+You need an xAI API key from [console.x.ai](https://console.x.ai).
+
+## Configure in Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "grok": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@pkwadsy/grok-mcp"],
+      "env": {
+        "XAI_API_KEY": "your-xai-api-key"
+      }
+    }
+  }
+}
+```
+
+## Tool: `ask_grok`
+
+Single tool with options for different use cases.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | yes | The question or task for Grok |
+| `system_prompt` | string | no | Custom system prompt |
+| `model` | string | no | Model to use (default: `grok-4.20-reasoning`) |
+| `web_search` | boolean | no | Enable real-time web search |
+| `x_search` | boolean | no | Enable X/Twitter search |
+
+### Available Models
+
+- `grok-4.20-reasoning` — flagship reasoning (default)
+- `grok-4.20-non-reasoning` — fast, no reasoning
+- `grok-4.20-multi-agent` — multi-agent mode, great for architecture and planning
+- `grok-4.1-fast-reasoning` — cheaper reasoning
+- `grok-4.1-fast-non-reasoning` — cheapest, fast
+
+### Examples
+
+**Ask a question:**
+```
+prompt: "What are the trade-offs between microservices and monoliths?"
+```
+
+**Deep architecture planning (multi-agent):**
+```
+prompt: "Design a system architecture for a real-time collaborative editor"
+model: "grok-4.20-multi-agent"
+```
+
+**Search the web:**
+```
+prompt: "What happened in tech news today?"
+web_search: true
+```
+
+**Search X/Twitter:**
+```
+prompt: "What are people saying about the new React release?"
+x_search: true
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const apiKey = process.env.XAI_API_KEY;
+if (!apiKey) {
+    console.error("XAI_API_KEY environment variable is required");
+    process.exit(1);
+}
+const server = new McpServer({
+    name: "grok-mcp",
+    version: "1.0.0",
+});
+async function callGrok(options) {
+    const model = options.model ?? "grok-4.20-reasoning";
+    const body = {
+        model,
+        input: options.messages,
+    };
+    if (options.tools && options.tools.length > 0) {
+        body.tools = options.tools;
+    }
+    const response = await fetch("https://api.x.ai/v1/responses", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Grok API error (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    for (const item of data.output) {
+        if (item.type === "message" && item.content) {
+            for (const block of item.content) {
+                if (block.type === "output_text" && block.text) {
+                    return block.text;
+                }
+            }
+        }
+    }
+    throw new Error("No text content in Grok response");
+}
+server.tool("ask_grok", "Ask Grok a question. Grok is great for thinking, planning, architecture, and real-time search via web and X/Twitter. Use web_search for current information from the internet. Use x_search to find and analyze posts on X/Twitter.", {
+    prompt: z.string().describe("The question or task for Grok"),
+    system_prompt: z
+        .string()
+        .optional()
+        .describe("Custom system prompt to guide Grok's behavior"),
+    model: z
+        .string()
+        .optional()
+        .describe("Model to use. Defaults to grok-4.20-reasoning. Options: grok-4.20-reasoning, grok-4.20-non-reasoning, grok-4.20-multi-agent, grok-4.1-fast-reasoning, grok-4.1-fast-non-reasoning"),
+    web_search: z
+        .boolean()
+        .optional()
+        .describe("Enable web search for real-time internet information"),
+    x_search: z
+        .boolean()
+        .optional()
+        .describe("Enable X/Twitter search to find and analyze posts"),
+}, async ({ prompt, system_prompt, model, web_search, x_search }) => {
+    const messages = [];
+    if (system_prompt) {
+        messages.push({ role: "system", content: system_prompt });
+    }
+    messages.push({ role: "user", content: prompt });
+    const tools = [];
+    if (web_search) {
+        tools.push({ type: "web_search" });
+    }
+    if (x_search) {
+        tools.push({ type: "x_search" });
+    }
+    const response = await callGrok({
+        messages,
+        model,
+        tools: tools.length > 0 ? tools : undefined,
+    });
+    return {
+        content: [{ type: "text", text: response }],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pkwadsy/grok-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that wraps the xAI Grok API — delegate thinking, planning, and search to Grok",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "grok-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "grok",
+    "xai",
+    "ai",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}