<p align="center">
  <img src="assets/logo.svg" alt="x-api logo" width="96" height="96" />
</p>

<h1 align="center">x-api</h1>

<p align="center"><strong>X API plugin for Grok App, Grok Build, and Codex</strong></p>
<p align="center"><em>Post · Engage · DMs · Media · Own-account reads — public search stays on Grok <code>x_search</code></em></p>
<p align="center">
  <a href="https://grok-app.com">https://grok-app.com</a>
  ·
  <a href="https://github.com/RongleCat/grok-app">Grok App</a>
</p>

<p align="center">
  <a href="./README.md">English</a> ·
  <a href="./README_ZH.md">中文</a>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
  <a href="https://github.com/RongleCat/x-api/stargazers"><img src="https://img.shields.io/github/stars/RongleCat/x-api?style=social" alt="GitHub stars" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D18.18-brightgreen" alt="Node 18+" />
  <img src="https://img.shields.io/badge/hosts-Grok%20App%20%7C%20Grok%20Build%20%7C%20Codex-0ea5e9" alt="Hosts" />
  <img src="https://img.shields.io/badge/note-unofficial-yellow" alt="Unofficial" />
</p>

<p align="center">
  <a href="https://x.com/cgnot996"><img src="https://img.shields.io/badge/X-铁柱AGI%20%40cgnot996-black?logo=x&logoColor=white" alt="X 铁柱AGI" /></a>
  <img src="https://img.shields.io/badge/WeChat-铁柱AGI-07C160?logo=wechat&logoColor=white" alt="WeChat 铁柱AGI" />
</p>

<p align="center">
  <img src="assets/wechat/mp-search-scan.png" alt="WeChat Search 铁柱AGI — scan to follow" width="420" />
  &nbsp;&nbsp;
  <img src="assets/wechat/community-group-qr.png" alt="WeChat group QR — scan to join" width="200" />
</p>

---

> [!NOTE]
> **Not an official xAI or X product.** This is an open-source plugin by [铁柱AGI / RongleCat](https://github.com/RongleCat) for the local [Grok App](https://github.com/RongleCat/grok-app) workbench and OpenAI Codex. It talks to **X API v2** with *your* developer App credentials. Public lookups should stay on Grok subscription tools (`x_search` / `x_keyword_search` / …) so you do not spend pay-per-use credits on search.

Background write-up: [用积分刀刃上的授权流程](https://x.com/cgnot996/status/2094220949340185078) (@cgnot996).

---

## Contents

- [Why this plugin](#why-this-plugin)
- [Auth (shorter than the 12-step PIN)](#auth-shorter-than-the-12-step-pin)
- [Install](#install)
- [Authorize](#authorize)
- [Credits](#credits)
- [MCP tools](#mcp-tools)
- [Layout](#layout)
- [Development](#development)
- [Security](#security)
- [Related projects](#related-projects)
- [License & author](#license--author)

---

## Why this plugin

| Job | Use |
|---|---|
| Search X / Twitter publicly | Grok built-in `x_search`, `x_keyword_search`, `x_semantic_search`, `x_user_search`, `x_thread_fetch` (subscription, no X developer credits) |
| Post, reply, like, follow, DMs, lists, your own data | **This plugin** (pay-per-use X API) |
| Official hosted MCP `https://api.x.com/mcp` (`xurl`) | Incomplete for posting; not a substitute |

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.

| Order | Path | When | Why it is shorter |
|---|---|---|---|
| **1 (default)** | Four console tokens | You operate the account that owns the App | No authorize URL, no PIN, tokens do not expire |
| **2** | OAuth 2.0 PKCE localhost | One browser Allow + refresh | Callback `http://127.0.0.1:8787/callback`; Native App secret empty |
| **3** | OAuth 1.0a localhost | Same keys, no PIN | User token does not expire |
| **4** | PIN / oob | No localhost | Same as the original article steps 8–11 |
| **5** | Bearer | Public reads only | Cannot post |

---

## 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:

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

Local checkout:

```bash
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:

```bash
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:

```bash
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):

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

Env vars: see [`.env.example`](./.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

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

No `npm install` required for runtime.

---

## Security

See [SECURITY.md](./SECURITY.md). Report privately on X [@cgnot996](https://x.com/cgnot996) or via GitHub Security Advisories. Never file tokens in public issues.

---

## Related projects

| Project | Link |
|---|---|
| **Grok App** | [RongleCat/grok-app](https://github.com/RongleCat/grok-app) · [grok-app.com](https://grok-app.com) |
| **GrokGo** | [RongleCat/grok-go](https://github.com/RongleCat/grok-go) |
| **awesome-grok-bot** | [RongleCat/awesome-grok-bot](https://github.com/RongleCat/awesome-grok-bot) |

---

## License & author

[MIT](./LICENSE) © 2026 RongleCat.

| Channel | Link |
|:---|:---|
| 𝕏 **X (Twitter)** | [@cgnot996 (铁柱AGI)](https://x.com/cgnot996) |
| 📢 **WeChat Official Account** | Search **「铁柱AGI」** or scan the top-left QR |
| 💬 **WeChat community** | Scan the top-right QR |
| 🐙 **GitHub** | [RongleCat](https://github.com/RongleCat) |

⭐ If this plugin saves you X API credits, please star the repo — and [Grok App](https://github.com/RongleCat/grok-app).