# Apidance MCP 中文说明

`apidance-mcp` 是一个本地 stdio MCP 服务，用来把 Apidance 文档中 `twitter-api` 菜单下的接口暴露给 Codex、Claude Code、Claude Desktop 以及其他支持 MCP 的客户端使用。

这个服务只依赖 Node.js 内置能力，不需要安装 MCP SDK 或其他 npm 依赖。

需要购买 Apidance API key，请直接联系 Telegram 用户 [@shingle](https://t.me/shingle)。

价格：

| 请求次数 | 价格 |
| --- | --- |
| 10k requests | $8 |
| 100k requests | $40 |
| 1000k requests | $200 |

npm 包名：`@apidance/mcp`

可执行命令：`apidance-mcp`

## 功能概览

服务会暴露两类工具：

- `apidance_call`：通用调用工具，通过 `endpoint` 参数选择任意 Apidance Twitter API 端点。
- `twitter_*`：每个接口对应一个专用工具，例如 `twitter_simple_search`、`twitter_graphql_search_timeline`、`twitter_graphql_create_tweet`。
- `skills/apidance-discover-twitter-team/`：随 npm 包发布的 Codex Skill，用于发现并核验官方 X/Twitter 账号背后的团队和相关生态账号。

同时也提供 MCP resources：

- `apidance://twitter/endpoints`：当前内置的端点 registry。
- `apidance://twitter/usage`：简短使用说明。
- `apidance://twitter/data-cleaning`：清洗脚本说明，包含输入接口来源和输出格式。
- `apidance://twitter/data-cleaning.zh-CN`：中文清洗脚本说明。
- `apidance://twitter/scripts/clean-user-tweets.mjs`：可直接运行的用户推文清洗脚本源码。
- `apidance://twitter/scripts/twitter-normalize.mjs`：可 import 的 Twitter GraphQL 归一化工具源码。
- `apidance://twitter/skills`：随包发布的 Skill 列表。
- `apidance://twitter/skills.zh-CN`：中文 Skill 列表。
- `apidance://twitter/skills/apidance-discover-twitter-team/SKILL.md`：Twitter team discovery Skill 说明。
- `apidance://twitter/skills/apidance-discover-twitter-team/README.md`：Twitter team discovery Skill 的英文 README。
- `apidance://twitter/skills/apidance-discover-twitter-team/README.zh-CN.md`：Twitter team discovery Skill 的中文 README。

## 目录结构

```text
apidance-mcp/
  bin/apidance-mcp.js          # MCP 服务入口
  src/server.js                # stdio MCP 协议和 HTTP 调用逻辑
  src/endpoints.js             # Apidance twitter-api 端点清单
  docs/API.md                  # 英文接口参考
  docs/DATA_CLEANING.md        # 英文清洗脚本说明
  docs/DATA_CLEANING.zh-CN.md  # 中文清洗脚本说明
  docs/INSTALL.md              # 英文安装说明
  docs/SECURITY.md             # 英文安全说明
  examples/                    # Codex、Claude Code、Claude Desktop 配置示例
  public-scripts/data-cleaning/ # 可复用清洗脚本
  skills/apidance-discover-twitter-team/ # 可安装到 Codex 的团队发现 Skill
```

## 运行要求

- Node.js 18.18 或更新版本。
- Apidance API key。
- 如果需要操作自己的 Twitter/X 账号，例如发推、转推、点赞、收藏、查看通知，需要提供 Twitter/X cookie 中的 `auth_token` 值。

## 快速开始

面向普通用户，推荐在发布到 npm 后通过 `npx` 使用，不需要下载 GitHub 源码：

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

也可以全局安装：

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

从源码运行主要适合开发、审计或本地修改：

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

查看当前暴露的工具列表：

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

清洗脚本会随 npm 包一起发布，也可以通过 MCP resources 读取：

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

Twitter team discovery Skill 也会随 npm 包发布：

```text
skills/apidance-discover-twitter-team/
```

在 npm 包根目录下可以直接运行它的服务脚本：

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

这个 Skill 内部使用 `public-scripts/data-cleaning/twitter-normalize.mjs` 作为公共归一化/清洗代码，不再维护第二份私有清洗实现。如果把 Skill 文件夹复制到 `~/.codex/skills` 独立使用，运行脚本时需要保留 `@apidance/mcp` 包，并设置 `APIDANCE_MCP_PACKAGE_ROOT` 指向该包根目录。

Skill 文档：

- [Skill 列表](../skills/README.zh-CN.md)
- [Twitter team discovery Skill 中文 README](../skills/apidance-discover-twitter-team/README.zh-CN.md)
- [Twitter team discovery Skill 指令](../skills/apidance-discover-twitter-team/SKILL.md)

Skill resources：

```text
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.zh-CN.md
```

## 环境变量

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `APIDANCE_API_KEY` | 是 | Apidance API key，会作为请求头 `apikey` 发送。 |
| `APIDANCE_AUTH_TOKEN` | 否 | Twitter/X 账号 cookie 里的 `auth_token` 值，会作为请求头 `AuthToken` 发送。只在需要账号操作时设置。 |
| `APIDANCE_USE_PROXY` | 否 | Apidance 的 `UseProxy` 请求头，例如 `http://username:password@host:port`。 |
| `APIDANCE_TIMEOUT_MS` | 否 | 单次 HTTP 请求超时时间，默认 `30000` 毫秒。 |

工具调用时也可以通过参数临时覆盖环境变量：

- `api_key`
- `auth_token`
- `use_proxy`
- `timeout_ms`

## 鉴权方式

所有接口都会自动添加：

```text
apikey: <APIDANCE_API_KEY>
```

当配置了 `APIDANCE_AUTH_TOKEN` 或工具参数 `auth_token` 时，会额外添加：

```text
AuthToken: <twitter-auth-token-cookie-value>
```

`AuthToken` 是可选的，但账号操作通常需要它。它应该填写 Twitter/X cookie 中 `auth_token` 这一项的值，不需要带 `auth_token=` 前缀。

## Codex 安装

把下面配置加入 `~/.codex/config.toml`，或你正在使用的项目级 Codex 配置中：

```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"
```

修改配置后重启 Codex。不要把真实 `APIDANCE_API_KEY` 或 `APIDANCE_AUTH_TOKEN` 提交到仓库。

如果是从本地源码运行，而不是从 npm 安装，可以使用本地脚本路径：

```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 安装

本地私有配置：

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

项目级 `.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:-}",
        "APIDANCE_TIMEOUT_MS": "30000"
      },
      "timeout": 600000
    }
  }
}
```

Claude Code 对项目级 `.mcp.json` 通常会要求你确认信任后才会启用。

## Claude Desktop 安装

在 Claude Desktop 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "apidance-mcp": {
      "command": "npx",
      "args": ["-y", "@apidance/mcp"],
      "env": {
        "APIDANCE_API_KEY": "your-apidance-api-key",
        "APIDANCE_AUTH_TOKEN": ""
      }
    }
  }
}
```

修改配置后重启 Claude Desktop。

## 工具调用方式

### 通用工具 `apidance_call`

所有接口都可以通过 `apidance_call` 调用。只需要指定 `endpoint`：

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

### 专用工具 `twitter_*`

同一个请求也可以直接调用专用工具 `twitter_simple_search`：

```json
{
  "q": "eth",
  "sort_by": "Latest"
}
```

专用工具的好处是模型更容易从工具名判断接口用途；通用工具的好处是自动化脚本里更统一。

## 常用示例

### 搜索推文 Simple API

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

### GraphQL 搜索时间线

GET 类 GraphQL 接口可以传 `variables` 对象，服务会自动把它 JSON 字符串化后放到 URL query 的 `variables` 参数里。

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

### 查询用户信息

```json
{
  "endpoint": "graphql_user_by_screen_name",
  "variables": {
    "screen_name": "elonmusk"
  }
}
```

或使用 Twitter 1.1 风格接口：

```json
{
  "endpoint": "v11_users_show",
  "screen_name": "elonmusk"
}
```

### 查询文章推文 TweetDetail

如果 `TweetDetail` 查询的是文章推文，需要把 `fieldToggles` 作为和 `variables` 同级的 query 参数传入：

```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
  }
}
```

### 查询账号附属账号列表

`UserBusinessProfileTeamTimeline` 用于查询某个账号的附属账号列表：

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

### 发推

发推属于账号操作，通常需要 `AuthToken`。

```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
  }
}
```

如果已在环境变量里配置 `APIDANCE_AUTH_TOKEN`，调用时可以省略 `auth_token`。

### 上传媒体

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

也可以使用 base64：

```json
{
  "endpoint": "upload_media",
  "file_base64": "base64-content",
  "filename": "image.png",
  "mime_type": "image/png"
}
```

### 查询剩余调用次数

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

这个接口路径是 `/key/{apikey}`，服务默认会用 `APIDANCE_API_KEY` 填入路径，并在返回结果里的请求 URL 中做脱敏。

### 自定义 GraphQL endpoint

```json
{
  "endpoint": "custom_api_endpoint",
  "graphql_id": "api endpoint graphql id",
  "api_path": "api path",
  "variables": {
    "screen_name": "elonmusk"
  }
}
```

## 已支持的端点分组

### 1.1

| endpoint | tool | 说明 |
| --- | --- | --- |
| `v11_users_show` | `twitter_v11_users_show` | 查询用户信息。 |
| `v11_followers_list` | `twitter_v11_followers_list` | 查询粉丝列表。 |
| `v11_friends_list` | `twitter_v11_friends_list` | 查询关注列表。 |

### GraphQL

| endpoint | tool |
| --- | --- |
| `graphql_create_tweet` | `twitter_graphql_create_tweet` |
| `graphql_create_note_tweet` | `twitter_graphql_create_note_tweet` |
| `graphql_create_retweet` | `twitter_graphql_create_retweet` |
| `graphql_quote_tweet` | `twitter_graphql_quote_tweet` |
| `graphql_favorite_tweet` | `twitter_graphql_favorite_tweet` |
| `graphql_create_bookmark` | `twitter_graphql_create_bookmark` |
| `graphql_home_latest_timeline` | `twitter_graphql_home_latest_timeline` |
| `graphql_search_timeline` | `twitter_graphql_search_timeline` |
| `graphql_audio_space_search` | `twitter_graphql_audio_space_search` |
| `graphql_audio_space_by_id` | `twitter_graphql_audio_space_by_id` |
| `graphql_tweet_detail` | `twitter_graphql_tweet_detail` |
| `graphql_tweet_result_by_rest_id` | `twitter_graphql_tweet_result_by_rest_id` |
| `graphql_user_by_screen_name` | `twitter_graphql_user_by_screen_name` |
| `graphql_user_by_rest_id` | `twitter_graphql_user_by_rest_id` |
| `graphql_user_tweets` | `twitter_graphql_user_tweets` |
| `graphql_user_tweets_and_replies` | `twitter_graphql_user_tweets_and_replies` |
| `graphql_user_media` | `twitter_graphql_user_media` |
| `graphql_followers` | `twitter_graphql_followers` |
| `graphql_following` | `twitter_graphql_following` |
| `graphql_followers_you_know` | `twitter_graphql_followers_you_know` |
| `graphql_retweeters` | `twitter_graphql_retweeters` |
| `graphql_list_latest_tweets_timeline` | `twitter_graphql_list_latest_tweets_timeline` |
| `graphql_profile_spotlights_query` | `twitter_graphql_profile_spotlights_query` |
| `graphql_communities_fetch_one_query` | `twitter_graphql_communities_fetch_one_query` |
| `graphql_community_members` | `twitter_graphql_community_members` |
| `graphql_community_tweets_timeline` | `twitter_graphql_community_tweets_timeline` |
| `graphql_blue_verified_followers` | `twitter_graphql_blue_verified_followers` |
| `graphql_ai_trend_by_rest_id` | `twitter_graphql_ai_trend_by_rest_id` |
| `graphql_trend_relevant_users` | `twitter_graphql_trend_relevant_users` |
| `graphql_user_business_profile_team_timeline` | `twitter_graphql_user_business_profile_team_timeline` |

### Simple API

| endpoint | tool | 说明 |
| --- | --- | --- |
| `simple_tweet_detail` | `twitter_simple_tweet_detail` | 精简版推文详情。 |
| `simple_user_tweets` | `twitter_simple_user_tweets` | 精简版用户推文列表。 |
| `simple_retweeters` | `twitter_simple_retweeters` | 精简版转推用户列表。 |
| `simple_quotes` | `twitter_simple_quotes` | 精简版引用推文列表。 |
| `simple_search` | `twitter_simple_search` | 精简版搜索。 |

### Notifications

这些接口在 Apidance 文档中标记为 `developing`，通常需要 `AuthToken`。

| endpoint | tool |
| --- | --- |
| `notifications_all` | `twitter_notifications_all` |
| `notifications_mentions` | `twitter_notifications_mentions` |
| `notifications_verified` | `twitter_notifications_verified` |

### 其他

| endpoint | tool | 说明 |
| --- | --- | --- |
| `upload_media` | `twitter_upload_media` | 上传媒体文件。 |
| `remaining_calls` | `twitter_remaining_calls` | 查询 API key 剩余调用次数。 |
| `custom_api_endpoint` | `twitter_custom_api_endpoint` | 自定义 GraphQL endpoint。 |

## 返回格式

所有工具都会返回 JSON 文本，结构类似：

```json
{
  "endpoint": {
    "id": "simple_search",
    "title": "Search",
    "category": "simple api",
    "method": "GET",
    "url": "https://api.apidance.pro/sapi/Search?q=eth",
    "docs_url": "https://doc.apidance.pro/search-11279446e0.md"
  },
  "status": 200,
  "ok": true,
  "headers": {
    "content-type": "application/json"
  },
  "data": {}
}
```

当 `ok` 为 `false` 时，MCP 工具结果会被标记为错误，但仍会尽量返回 HTTP 状态码、响应头和响应体，方便排查。

## 安全注意事项

- 不要把真实 `APIDANCE_API_KEY`、`APIDANCE_AUTH_TOKEN` 或代理账号密码提交到仓库。
- 优先使用 MCP 客户端的环境变量配置传入密钥，少用工具参数直接传密钥，因为部分客户端可能记录工具输入。
- 会改变账号状态的工具建议在 MCP 客户端里设置确认规则，例如发推、转推、点赞、收藏、上传媒体。
- 服务会从返回的请求 URL 中脱敏 `APIDANCE_API_KEY`、`APIDANCE_AUTH_TOKEN`、`APIDANCE_USE_PROXY`。

高影响账号操作工具包括：

- `twitter_graphql_create_tweet`
- `twitter_graphql_create_note_tweet`
- `twitter_graphql_create_retweet`
- `twitter_graphql_quote_tweet`
- `twitter_graphql_favorite_tweet`
- `twitter_graphql_create_bookmark`
- `twitter_upload_media`

## 本地验证

语法检查：

```bash
cd /Users/guang/ws/web3/apidance/apidance-mcp
npm run check
```

手动初始化 MCP 服务：

```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | APIDANCE_API_KEY=test node ./bin/apidance-mcp.js
```

能看到 `initialize` 响应和 `tools/list` 响应就说明服务可以被 MCP 客户端正常启动。

## 参考

- Apidance 文档：https://doc.apidance.pro
- Apidance LLM 文档索引：https://doc.apidance.pro/llms.txt
- 英文接口参考：[API.md](./API.md)
- 英文安装说明：[INSTALL.md](./INSTALL.md)
- Skill 列表：[skills/README.zh-CN.md](../skills/README.zh-CN.md)
- 发布说明：[PUBLISH.md](./PUBLISH.md)
- 英文安全说明：[SECURITY.md](./SECURITY.md)