Apidance MCP

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

中文说明

Need an Apidance API key? Contact Telegram user @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:

npx -y @apidance/mcp

Or install it globally:

npm install -g @apidance/mcp
apidance-mcp

For local development from source:

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

List exposed tools:

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:

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
• Twitter team discovery Skill README
• Twitter team discovery Skill instructions

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:

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

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

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:

{
  "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:

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

GraphQL GET convenience:

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

TweetDetail for article tweets:

{
  "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:

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

GraphQL POST convenience:

{
  "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:

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

Check remaining calls:

{
  "endpoint": "remaining_calls"
}

Documentation

• Installation guide
• Endpoint reference
• Data cleaning scripts
• Bundled Skills
• Publishing guide
• Security notes

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.