x-api

Background write-up: 用积分刀刃上的授权流程 (@cgnot996).

Contents

• Why this plugin

• Auth (shorter than the 12-step PIN)

• Install

• Authorize

• Credits

• MCP tools

• Layout

• Development

• Security

• Related projects

• License & author

Related MCP server: mcp-x

Why this plugin

Zero runtime npm dependencies. Node 18+. Credentials live in ~/.x-api/credentials.json (mode 0600).

Auth (shorter than the 12-step PIN)

You still create a developer App once (Read and write, Native App, callback, website URL). What this plugin shortens is authorization, not the console.

Install

Requires Node 18+.

Grok App (recommended)

1. Open Settings → Extensions → Plugins

2. Under Recommended, install X API (never auto-installs)

3. Confirm trust

4. Settings → Extensions → MCP → From plugins → x-api → Authorize

5. Start a new conversation so tools inject (x-api__status, x-api__create_post, …)

CLI equivalent:

grok plugin install --trust https://github.com/RongleCat/x-api
grok plugin enable x-api

Local checkout:

grok plugin install --trust /path/to/x-api
grok plugin enable x-api

Codex

The repo includes .codex-plugin/plugin.json. Install from the local path or git URL, or:

node scripts/register-mcp.mjs codex

Authorize

Do not paste secrets into chat.

In Grok App: MCP row Authorize (console four tokens, or browser OAuth 2).

Terminal:

node scripts/x-api.mjs login --tokens    # shortest, App-owner account
node scripts/x-api.mjs login --oauth2    # one Allow
node scripts/x-api.mjs login --oauth1
node scripts/x-api.mjs login --pin
node scripts/x-api.mjs status
node scripts/x-api.mjs whoami
node scripts/x-api.mjs logout

Non-interactive (used by Grok App):

node scripts/x-api.mjs login --tokens --no-prompt \
  --api-key … --api-secret … --access-token … --access-token-secret …

Env vars: see .env.example. HTTP(S)_PROXY is honored when exchanging OAuth codes (Node fetch does not use the system proxy by default).

Credits

Same split as the original article:

• Read/search the public firehose: Grok subscription tools — do not put lookups through this plugin

• Write / read your own account: this MCP (~$0.015 per plain post)

• Do not put hostnames in the post body: x.com is auto-linked; cost jumps to ~$0.20

create_post rejects hostnames unless confirm_url_billing=true.

MCP tools

Post, delete, media, like/retweet/follow, bookmarks, hide replies, followers, mute/block, DMs, lists, trends, usage, whoami. Anything else: generic request with confirm_spend.

In a Grok session, tools are named x-api__<tool> (for example x-api__create_post).

Stdio speaks NDJSON for Grok App / Grok Build (same as official-aux). Content-Length is still accepted for Claude/Codex-style hosts.

Endpoint index: https://docs.x.com/x-api/llms.txt

Layout

.grok-plugin/plugin.json    Grok App / Grok Build
.codex-plugin/plugin.json   Codex
.mcp.json                   stdio MCP → mcp/server.mjs
skills/                     x-api + x-auth
commands/x-auth.md
mcp/                        zero-dep Node implementation
scripts/x-api.mjs           auth CLI

Development

npm test              # node --test
npx grok plugin validate .

No npm install required for runtime.

Security

See SECURITY.md. Report privately on X @cgnot996 or via GitHub Security Advisories. Never file tokens in public issues.

Related projects

License & author

MIT © 2026 RongleCat.

⭐ If this plugin saves you X API credits, please star the repo — and Grok App.