grok-bot-mcp
Provides tools for listing local SQLite database files and their disk sizes, and reading raw transcript entries from SQLite databases offline. Enforces read-only access via PRAGMA query_only = 1.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grok-bot-mcp What's my current usage?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
grok-bot
The Unified CLI & MCP Server for Grok Bot and Cursor.
Usage dashboard for humans. Complete MCP toolset for AI agents. Zero passwords. Zero keychain prompts.
๐ Why grok-bot?
For Humans (CLI): Check weekly usage %, quota limits, on-demand spend, and reset times across all accounts with one simple command. Connect accounts in seconds via browser login โ zero passwords or system keychain popups.
For AI Agents (MCP Server): Connects Claude Desktop, Cursor, Antigravity, Windsurf, Cline, and VS Code Copilot to Grok Bot. Lets your agents inspect usage, switch accounts, launch bots, read transcripts, send prompts, and search conversation history.
Zero Dependencies: 100% native Node.js built-ins. Pure ESM.
Related MCP server: grokbot-mcp
โก Quick Start (10 Seconds)
1. Install
One single command sets up the CLI and auto-configures your AI agents:
curl -fsSL https://raw.githubusercontent.com/Kargatharaakash/grok-bot-mcp/main/install.sh | sh2. Connect Your Account (Zero Passwords)
Authenticate in your browser via OAuth PKCE:
grok-bot login(Opens your default web browser to authorize. Zero passwords or keychain prompts.)
3. Check Usage
grok-botOutputs a clean, formatted usage dashboard:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ main [active] user@example.com โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Weekly Usage: 5.56% used โ
โ Available: Yes โ
โ Resets: Wed, Sep 9, 11:57 AM โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ On-demand: $0.00 used โ
โ Limit: No limit โ
โ Remaining: N/A โ
โ Cycle ends: Thu, Sep 24, 12:53 PM โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ๐ป Commands for Humans
Command | Description |
| View usage summary table for active or all accounts |
| Check usage for a specific account (e.g. |
| Sign in via browser OAuth (zero passwords, zero keychain) |
| Sign in and assign a custom nickname (e.g. |
| Switch the active account (alias: |
| List all saved accounts and token expiration dates |
| Remove a saved account |
| Output usage metrics as structured JSON for scripts & automation |
| Display built-in CLI help |
(Note: gbm and grok-bot-mcp work as exact aliases for grok-bot.)
๐ค MCP Server for AI Agents
When spawned by an AI client or with grok-bot mcp, grok-bot runs as a Model Context Protocol (MCP) server over standard input/output (stdio).
Automatically Configured AI Agents
The installer automatically configures:
Cursor:
~/.cursor/mcp.jsonClaude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.jsonAntigravity:
~/.gemini/config/mcp_config.jsonWindsurf:
~/.codeium/windsurf/mcp_config.jsonCline:
~/.cline/mcp_settings.jsonContinue:
~/.continue/config.jsonClaude Code:
claude mcp add
Manual Configuration
Add this to your MCP configuration file:
{
"mcpServers": {
"grok-bot": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/.gbm/bin/grok-bot-mcp"]
}
}
}๐ ๏ธ MCP Tools Reference
Tool | Category | What it does | Parameters |
| Usage | Check weekly usage %, quota limits, reset dates, and on-demand spend. |
|
| Usage | Switch the active account for Cursor / Grok Bot. |
|
| Agent | List all Grok Bot agents currently registered or running. | None |
| Agent | Launch a new Grok Bot agent instance with a name and prompt. |
|
| Agent | Delete a Grok Bot agent by its agent ID. |
|
| Messaging | Send a message to a bot and get its response. |
|
| Messaging | Read full conversation history of any bot in order. |
|
| Search | Search for bots by name or description. |
|
| Search | Full-text search across all local bot conversations. |
|
| Database | List local SQLite database files and disk sizes. | None |
| Database | Read raw SQLite database transcript entries offline. |
|
๐ Security & Privacy
Zero Passwords / Zero Keychain Dialogs: Browser PKCE login uses standard Web OAuth. Your operating system keychain is never prompted.
Encrypted Token Storage: Tokens are stored with restricted permissions (
0600) at~/.gbm/accounts.json.Read-Only SQLite Access: Database readers enforce
PRAGMA query_only = 1.No Telemetry: No analytics or tracking. Network communication occurs strictly with official endpoints (
api2.cursor.shand local/cloud gateway).
๐งช Testing
The test suite runs 100% offline with mocks โ zero network calls, zero modifications to running bots:
node --test tests/*.test.mjs๐ License
MIT ยฉ Aakash Kargathara
Available Tools
11 toolscheck_usageA
Check weekly usage, quota percentage, remaining requests, and on-demand spend for Cursor / Grok Bot accounts. If account='all', returns usage for all saved accounts.
Inputs: account.
create_botC
Create a new Grok Bot agent instance with a specific name and task description.
Inputs: name (required), description.
delete_botC
Permanently delete a Grok Bot agent by its agent ID.
Inputs: agentId (required).
get_transcriptB
Read the conversation transcript of a Grok Bot agent in chronological order.
Inputs: agentId (required), limit.
list_botsA
List all Grok Bot agents (bots) currently running or registered on this machine. Returns agent IDs, names, origins, and descriptions.
Inputs: no named parameters.
list_databasesA
List all local Grok Bot SQLite database files on this machine, showing agent IDs and file sizes.
Inputs: no named parameters.
read_transcript_entriesB
Directly read raw transcript entries from a bot's local SQLite database without network overhead.
Inputs: agentId (required), limit.
search_botsB
Search for Grok Bot agents matching a keyword in their name or description.
Inputs: query (required).
search_messagesC
Search across all local bot transcripts for messages containing a keyword.
Inputs: query (required), limit.
send_messageB
Send a message or user prompt to a Grok Bot agent and receive its response.
Inputs: agentId (required), message (required).
switch_accountA
Switch the active account for Cursor / Grok Bot across both CLI/MCP and the macOS Grok Bot desktop application. Next time you open the Grok Bot desktop app, it will launch directly into this account.
Inputs: account (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 11 tools
Most tools target clear distinct operations (account vs bot lifecycle vs transcript vs database). However, get_transcript, read_transcript_entries, and search_messages all operate over transcript data, and list_bots vs search_bots overlap, which could cause occasional misselection.
All 11 tools follow a consistent snake_case verb_noun pattern (check_usage, switch_account, list_bots, create_bot, delete_bot, send_message, get_transcript, search_bots, list_databases, read_transcript_entries, search_messages). No mixed conventions.
11 tools is well within the ideal 3-15 range and each covers a meaningful slice of the domain (accounts, bots, transcripts, databases). Nothing feels redundant or padded.
Core lifecycle is covered: list/search/create/delete bots, send/get messages, and query databases. Minor gaps exist, e.g. no update_bot and no tool to add/list accounts beyond check_usage/switch_account, but agents can work around these.
Maintenance
Related MCP Connectors
Sandboxes, storage, secrets, queues, timers, locks, inboxes and run ledger for AI bots. One MCP.
AI agent platform: manage leads, conversations, bots, calendar and CRM via MCP.
Agent communication platform for agent to agent messaging via MCP. Messages, channels, skills.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients like Codex and Claude Code to start or continue conversations with Grok Build, track progress, read completed answers, and cancel running turns using an existing Grok login.1Apache 2.0
- AlicenseCqualityCmaintenanceEnables IDEs and MCP hosts to drive a user's Grok Bot cloud agents, including sending messages, waiting for replies, reading history, and managing agents, secrets, widgets, handoffs, and desktop access. It acts as an outbound bridge from Cursor, Claude, and VS Code to those cloud agents.21MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to invoke Grok Bot through a webhook and receive synchronous tool results from its asynchronous callbacks, with run management, cancellation, and budget guardrails.70 npm1MIT
- AlicenseAqualityBmaintenanceEnables any MCP client such as Cursor, Claude Code, or Codex to dispatch tasks to a Cursor Grok Bot running on its cloud computer, poll for its replies, and interrupt an in-progress run. It also lists the bots available for contact, without routing replies through an extra model.41MIT