# Apidance MCP

Dependency-free stdio MCP server for the Apidance `twitter-api` menu.

[中文说明](https://cdn.jsdelivr.net/npm/@apidance/mcp@latest/docs/README.zh-CN.md)

Need an Apidance API key? Contact Telegram user [@shingle](https://t.me/shingle).

Pricing:

| Requests | Price |
| --- | --- |
| 10k requests | $8 |
| 100k requests | $40 |
| 1000k requests | $200 |

The server exposes:

- `apidance_call`: one generic caller for every Apidance Twitter endpoint.
- `twitter_*` tools: one generated MCP tool per documented endpoint.
- MCP resources with the endpoint registry, short usage notes, and public data-cleaning scripts.
- A bundled Codex Skill at `skills/apidance-discover-twitter-team/` for verified Twitter team and ecosystem discovery.

The implementation uses only Node.js built-ins, so Codex, Claude Code, Claude Desktop, and other MCP clients can run it without installing an SDK package.

Package name: `@apidance/mcp`

Executable command: `apidance-mcp`

## Requirements

- Node.js 18.18 or newer.
- An Apidance API key.
- Optional Twitter/X `auth_token` cookie value when using account actions such as create tweet, retweet, like, bookmark, home timeline, or notifications.

## Quick Start

For end users, the recommended install mode is `npx` after this package is published to npm:

```bash
npx -y @apidance/mcp
```

Or install it globally:

```bash
npm install -g @apidance/mcp
apidance-mcp
```

For local development from source:

```bash
cd /Users/guang/ws/web3/apidance/apidance-mcp
npm run check
APIDANCE_API_KEY=your-apidance-api-key npm start
```

List exposed tools:

```bash
npm run list-tools
```

Data-cleaning scripts are bundled under `public-scripts/data-cleaning/` and exposed as MCP resources:

- `apidance://twitter/data-cleaning`
- `apidance://twitter/scripts/clean-user-tweets.mjs`
- `apidance://twitter/scripts/twitter-normalize.mjs`

The Twitter team discovery Skill is bundled under `skills/apidance-discover-twitter-team/` and uses the shared normalization helpers from `public-scripts/data-cleaning/twitter-normalize.mjs`.

Run the Skill service from the package root:

```bash
node skills/apidance-discover-twitter-team/scripts/run-discovery.mjs --help
```

If you copy the Skill folder into `~/.codex/skills`, keep `@apidance/mcp` installed and set `APIDANCE_MCP_PACKAGE_ROOT` to the package root when running its scripts.

Skill documentation:

- [Bundled Skill list](./skills/README.md)
- [Twitter team discovery Skill README](./skills/apidance-discover-twitter-team/README.md)
- [Twitter team discovery Skill instructions](./skills/apidance-discover-twitter-team/SKILL.md)

Skill resources:

- `apidance://twitter/skills`
- `apidance://twitter/skills.zh-CN`
- `apidance://twitter/skills/apidance-discover-twitter-team/SKILL.md`
- `apidance://twitter/skills/apidance-discover-twitter-team/README.md`

## Environment

| Variable | Required | Description |
| --- | --- | --- |
| `APIDANCE_API_KEY` | yes | Sent as request header `apikey`. |
| `APIDANCE_AUTH_TOKEN` | no | Sent as request header `AuthToken`. Use the value of your Twitter/X `auth_token` cookie only when operating your own account. |
| `APIDANCE_USE_PROXY` | no | Sent as request header `UseProxy`, for example `http://username:password@host:port`. |
| `APIDANCE_TIMEOUT_MS` | no | Per-request timeout. Defaults to `30000`. |

Per-call tool arguments `api_key`, `auth_token`, `use_proxy`, and `timeout_ms` can override environment values.

## Codex Setup

Add this to `~/.codex/config.toml` or the project-level Codex config you use:

```toml
[mcp_servers.apidance_mcp]
command = "npx"
args = ["-y", "@apidance/mcp"]
startup_timeout_sec = 30

[mcp_servers.apidance_mcp.env]
APIDANCE_API_KEY = "your-apidance-api-key"
APIDANCE_AUTH_TOKEN = ""
APIDANCE_TIMEOUT_MS = "30000"
```

Restart Codex after editing config.

If you are running from a local source checkout instead of npm, use:

```toml
[mcp_servers.apidance_mcp]
command = "node"
args = ["/Users/guang/ws/web3/apidance/apidance-mcp/bin/apidance-mcp.js"]
startup_timeout_sec = 30
```

## Claude Code Setup

Local user/private scope:

```bash
claude mcp add --transport stdio \
  --env APIDANCE_API_KEY=your-apidance-api-key \
  --env APIDANCE_AUTH_TOKEN= \
  apidance-mcp \
  -- npx -y @apidance/mcp
```

Project scope via `.mcp.json`:

```json
{
  "mcpServers": {
    "apidance-mcp": {
      "command": "npx",
      "args": ["-y", "@apidance/mcp"],
      "env": {
        "APIDANCE_API_KEY": "${APIDANCE_API_KEY}",
        "APIDANCE_AUTH_TOKEN": "${APIDANCE_AUTH_TOKEN:-}"
      },
      "timeout": 600000
    }
  }
}
```

Claude Code will ask you to approve project-scoped MCP servers from `.mcp.json`.

## Tool Usage

Generic call:

```json
{
  "endpoint": "simple_search",
  "query": {
    "q": "eth",
    "sort_by": "Latest"
  }
}
```

GraphQL GET convenience:

```json
{
  "endpoint": "graphql_search_timeline",
  "variables": {
    "rawQuery": "eth",
    "count": 40,
    "cursor": "",
    "querySource": "typed_query",
    "product": "Latest",
    "includePromotedContent": false
  }
}
```

TweetDetail for article tweets:

```json
{
  "endpoint": "graphql_tweet_detail",
  "variables": {
    "focalTweetId": "1694634492403843248",
    "referrer": "profile",
    "controller_data": "DAACDAABDAABCgABAAAAAAAAAAAKAAkAAAABFPY0+AAAAAA=",
    "with_rux_injections": false,
    "includePromotedContent": false,
    "withCommunity": true,
    "withQuickPromoteEligibilityTweetFields": true,
    "withBirdwatchNotes": true,
    "withVoice": true,
    "withV2Timeline": true
  },
  "fieldToggles": {
    "withArticleRichContentState": true,
    "withArticlePlainText": true
  }
}
```

Business profile affiliated accounts:

```json
{
  "endpoint": "graphql_user_business_profile_team_timeline",
  "variables": {
    "userId": "783214",
    "cursor": "",
    "count": 100,
    "teamName": "NotAssigned",
    "includePromotedContent": false,
    "withClientEventToken": false,
    "withVoice": true
  }
}
```

GraphQL POST convenience:

```json
{
  "endpoint": "graphql_create_tweet",
  "auth_token": "your-auth-token-cookie-value",
  "variables": {
    "tweet_text": "hello from MCP",
    "dark_request": false,
    "media": {
      "media_entities": [],
      "possibly_sensitive": false
    },
    "semantic_annotation_ids": [],
    "includePromotedContent": false
  }
}
```

Upload media:

```json
{
  "endpoint": "upload_media",
  "file_path": "/absolute/path/to/image.png",
  "mime_type": "image/png"
}
```

Check remaining calls:

```json
{
  "endpoint": "remaining_calls"
}
```

## Documentation

- [Installation guide](./docs/INSTALL.md)
- [Endpoint reference](./docs/API.md)
- [Data cleaning scripts](./docs/DATA_CLEANING.md)
- [Bundled Skills](./skills/README.md)
- [Publishing guide](./docs/PUBLISH.md)
- [Security notes](./docs/SECURITY.md)

## Source Documentation

This package is based on the Apidance public docs:

- https://doc.apidance.pro
- https://doc.apidance.pro/llms.txt

Only the `twitter-api` menu is included.