---
title: "SDK 与 MCP"
description: "TypeScript 和 Python SDK、适用于 Claude Code、Codex 和 Cursor 的 MCP 服务器，以及 OpenAPI 文档：所有 API，一个密钥。"
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

本文档中的一切都是普通的 HTTP，任何语言都能调用。以下是现成的接入方式。每一种都能访问所有 API：电商平台、社交平台、
搜索引擎、AI 回答引擎和图片翻译，使用同一个密钥，价格与直接调用相同。

## TypeScript

```bash
npm install @apinoa/sdk
```

```ts
import { ApinoaClient } from "@apinoa/sdk";

const apinoa = new ApinoaClient(); // 读取 APINOA_API_KEY

const { data } = await apinoa.amazon.search({ query: "wool socks", priceMax: 30 });
const posts = await apinoa.tiktok.posts({ username: "khaby.lame" });
const serp = await apinoa.google.search({ q: "trail running shoes", country: "US" });
const answer = await apinoa.chatgpt.answer({ prompt: "Best running shoes for beginners?", country: "US" });
```

每个调用都是 `apinoa.<platform>.<operation>(params)`，名称与 URL 一致：`/v1/google-aio/answer` 即
`apinoa.googleAio.answer(...)`。支持 Node.js 20 及以上、Bun、Deno 和 Cloudflare Workers。源码与参考：
[apinoahq/apinoa-typescript](https://github.com/apinoahq/apinoa-typescript)。

## Python

```bash
pip install apinoa
```

```python
from apinoa import Apinoa

client = Apinoa()  # 读取 APINOA_API_KEY

res = client.amazon.search(query="wool socks", price_max=30)
posts = client.tiktok.posts(username="khaby.lame")
serp = client.google.search(q="trail running shoes", country="US")
answer = client.chatgpt.answer(prompt="Best running shoes for beginners?", country="US")
```

同样的调用，使用 snake_case：`/v1/amazon/image-search` 即 `client.amazon.image_search(...)`，`priceMax` 即
`price_max`。内含异步客户端。需要 Python 3.9 及以上。源码与参考：
[apinoahq/apinoa-python](https://github.com/apinoahq/apinoa-python)。

## MCP 服务器

`apinoa-mcp` 把整个 API 作为工具交给 AI 助手：问它*"比较 Amazon 和 Walmart 上最便宜的 Stanley 40 oz"*或
*"问 ChatGPT 最好的跑鞋时，它会提到我们的品牌吗"*，它会替你发出调用。

### 托管版：无需安装

`https://api.apinoa.com/mcp` 是同一个服务器的托管版。无需复制密钥：客户端第一次连接时会在浏览器中打开 apinoa，
你登录并批准后，该客户端会获得一个专属密钥。该密钥 90 天后过期，显示在控制台 → API 密钥中，可随时吊销。

```bash
# Claude Code（添加后运行 /mcp 并选择 apinoa 登录）
claude mcp add --transport http apinoa https://api.apinoa.com/mcp

# Codex
codex mcp add apinoa --url https://api.apinoa.com/mcp
codex mcp login apinoa
```

**Claude.ai 和 Claude Desktop**：设置 → 连接器 → 添加自定义连接器，填入上面的 URL。
**Cursor 等其他客户端**：`{ "mcpServers": { "apinoa": { "url": "https://api.apinoa.com/mcp" } } }`。

如果想用已有的密钥代替登录，把它作为请求头发送：
`claude mcp add --transport http apinoa https://api.apinoa.com/mcp -H "Authorization: Bearer your_key"`。
托管服务器为每类读取提供一个工具（`search_products`、`get_product`、`list_social_posts`、`call_apinoa` 等）；
下面的本地服务器还可以运行模型编写的代码。

### 本地版：npx

**Claude Code**

```bash
claude mcp add apinoa -e APINOA_API_KEY=your_key -- npx -y apinoa-mcp
```

**Codex**

```bash
codex mcp add apinoa --env APINOA_API_KEY=your_key -- npx -y apinoa-mcp
```

**Gemini CLI**：安装时会询问你的密钥。

```bash
gemini extensions install https://github.com/apinoahq/apinoa-mcp
```

**Claude Code 插件**：包含 MCP 服务器，以及每个 API 一个技能，告诉助手何时使用、如何使用。

```text
/plugin marketplace add apinoahq/apinoa-skills
/plugin install apinoa@apinoa
```

同样的技能可以用 `npx skills add apinoahq/apinoa-skills` 安装到 Codex、Cursor 等其他助手。

**Cursor、Claude Desktop、Windsurf 等客户端**：添加到客户端的 MCP 配置（`.cursor/mcp.json`、
`claude_desktop_config.json` 等）中：

```json
{
  "mcpServers": {
    "apinoa": {
      "command": "npx",
      "args": ["-y", "apinoa-mcp"],
      "env": { "APINOA_API_KEY": "your_key" }
    }
  }
}
```

需要 Node.js 20 及以上。调用按正常费率计入该密钥，失败的调用不计费。源码、工具与选项：
[apinoahq/apinoa-mcp](https://github.com/apinoahq/apinoa-mcp)。

## OpenAPI

[`https://apinoa.com/openapi.json`](https://apinoa.com/openapi.json) 是整个 API 的 OpenAPI 3.1 文档：每个操作、
它的参数和响应类型。可以用它生成其他语言的客户端，或导入 Postman 或 API 网关。上面的 SDK 也是由它生成的。

[`GET https://gateway.apinoa.com/v1/marketplaces`](https://gateway.apinoa.com/v1/marketplaces) 是实时目录：每个
平台、它的操作、每个操作的费用以及接受的参数，以 JSON 返回，无需密钥。

## 面向 AI 编程助手

把下面这段粘贴到项目的 `AGENTS.md` 或 `CLAUDE.md` 中，编程助手就会调用 API，而不是自己编写爬虫。
这段是给助手读的，所以保留英文。

```markdown
## Web data: apinoa
Use the apinoa API instead of writing a scraper for marketplace, social, search-engine or AI-answer data.
- Call: `GET https://gateway.apinoa.com/v1/{platform}/{operation}` with header `x-api-key: $APINOA_API_KEY`
  (AI answers and image search are `POST` with a JSON body). Responses are `{ success, data }`; on failure
  `{ success: false, error: { code, message } }`. Branch on `error.code`. Failed calls are not billed.
- SDKs: TypeScript `@apinoa/sdk` (`new ApinoaClient()`, `apinoa.<platform>.<operation>(params)`),
  Python `apinoa` (`Apinoa()`, snake_case). MCP server: `npx -y apinoa-mcp`, or hosted at
  `https://api.apinoa.com/mcp` (OAuth sign-in, or `Authorization: Bearer <key>`).
- Which platform for what:
  - Products, prices, reviews: `amazon`, `walmart`, `shopify` (any store), `aliexpress`, `tiktokshop`
    (`search`, `product`, `reviews`, `categories`, `browse`)
  - Social profiles, posts, comments: `tiktok`, `instagram`, `youtube`, `reddit`, `x`, `threads`, `linkedin`
    (`profile`, `posts`, `post`, `comments`)
  - Search results: `google`, `bing`, `naver`, `baidu`, `yandex`, `yahoo`, `duckduckgo`, `google-shopping`,
    `google-trends`, `app-store`, `google-play`, `tripadvisor` (`search`, `places`, `reviews`)
  - What AI engines answer: `chatgpt`, `gemini`, `google-aio`, `google-ai-mode`, `naver-ai-brief`, `naver-ai-tab`
    (`answer`)
  - Text inside images: `POST /v1/image-translate/translate`
- Every platform, operation, parameter and cost: `GET https://gateway.apinoa.com/v1/marketplaces` (no key).
  Docs as markdown: https://apinoa.com/llms.txt
```

- [`/llms.txt`](https://apinoa.com/llms.txt) 以 markdown 链接列出每个文档页面，
  [`/llms-full.txt`](https://apinoa.com/llms-full.txt) 把它们全部放在一个文件中。
- 每个文档页面也以 markdown 形式提供于 `/en/docs-raw/<page>`，例如
  [`/en/docs-raw/getting-started`](https://apinoa.com/en/docs-raw/getting-started)。