Skip to main content
Glama

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.

license node deps mcp


๐ŸŒŸ 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 | sh

2. 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-bot

Outputs 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

grok-bot

View usage summary table for active or all accounts

grok-bot <name>

Check usage for a specific account (e.g. grok-bot company)

grok-bot login

Sign in via browser OAuth (zero passwords, zero keychain)

grok-bot login <name>

Sign in and assign a custom nickname (e.g. grok-bot login work)

grok-bot switch <name>

Switch the active account (alias: use)

grok-bot list

List all saved accounts and token expiration dates

grok-bot rm <name>

Remove a saved account

grok-bot --json

Output usage metrics as structured JSON for scripts & automation

grok-bot help

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.json

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Antigravity: ~/.gemini/config/mcp_config.json

  • Windsurf: ~/.codeium/windsurf/mcp_config.json

  • Cline: ~/.cline/mcp_settings.json

  • Continue: ~/.continue/config.json

  • Claude 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

check_usage

Usage

Check weekly usage %, quota limits, reset dates, and on-demand spend.

account (optional: account name or "all")

switch_account

Usage

Switch the active account for Cursor / Grok Bot.

account (required: name of account)

list_bots

Agent

List all Grok Bot agents currently registered or running.

None

create_bot

Agent

Launch a new Grok Bot agent instance with a name and prompt.

name (required), description (optional)

delete_bot

Agent

Delete a Grok Bot agent by its agent ID.

agentId (required)

send_message

Messaging

Send a message to a bot and get its response.

agentId (required), message (required)

get_transcript

Messaging

Read full conversation history of any bot in order.

agentId (required), limit (optional)

search_bots

Search

Search for bots by name or description.

query (required)

search_messages

Search

Full-text search across all local bot conversations.

query (required), limit (optional)

list_databases

Database

List local SQLite database files and disk sizes.

None

read_transcript_entries

Database

Read raw SQLite database transcript entries offline.

agentId (required), limit (optional)


๐Ÿ”’ 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.sh and 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 tools
check_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

    A3.5/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      Apache 2.0
    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      21
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      4
      1
      MIT