# Uapi Mcp

![Banner](https://raw.githubusercontent.com/AxT-Team/uapi-mcp/main/banner.png?v=20260309-4)

[![npm version](https://img.shields.io/npm/v/uapi-mcp?style=flat-square)](https://www.npmjs.com/package/uapi-mcp)
[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
[![Docs](https://img.shields.io/badge/Docs-uapis.cn-2EAE5D?style=flat-square)](https://uapis.cn/docs)
[![MCP](https://img.shields.io/badge/MCP-2025--06--18-7C3AED?style=flat-square)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)

> Official MCP (Model Context Protocol) server for the
> [uapis.cn](https://uapis.cn) public API platform. Exposes **100+ UAPI
> endpoints** — network lookups, text utilities, image processing,
> social-platform queries, translation, search — as agent tools over
> Streamable HTTP and stdio.

## English summary

**Hosted server** (managed, recommended for most agents):

```text
https://uapis.cn/mcp
```

| Wiring                                       | Snippet                                                                                                                                                          |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Desktop / Claude Code                 | `{"mcpServers":{"uapi":{"transport":"streamable-http","url":"https://uapis.cn/mcp"}}}`                                                                          |
| Cursor (`.cursor/mcp.json`)                  | `{"mcpServers":{"uapi":{"url":"https://uapis.cn/mcp"}}}`                                                                                                         |
| Stdio (npx)                                  | `npx -y uapi-mcp start --mode dynamic`                                                                                                                           |

**Local install** (stdio, fully offline):

```bash
npx -y uapi-mcp start --mode dynamic
# or
npm install -g uapi-mcp && uapi-mcp start --mode dynamic
```

Authentication:

- Free-tier endpoints work with no key.
- Paid endpoints need `X-API-Key`. Get a key at
  [uapis.cn/console](https://uapis.cn/console).

Discovery surfaces:

- Server card: <https://uapis.cn/.well-known/mcp/server-card.json>
- WebMCP descriptor: <https://uapis.cn/.well-known/webmcp>
- OpenAPI spec: <https://uapis.cn/openapi.json>
- LLM context bundle: <https://uapis.cn/llms.txt>

See [`AGENTS.md`](./AGENTS.md) for the full agent-facing playbook.

---

## 中文说明

Uapi Mcp 是 `uapis.cn` 的官方 MCP Server，把 UAPI 的搜索、翻译、图像、文本处理、网页解析能力整合成一个标准化接口，支持任何 MCP 协议客户端。

## 快速开始

### 方式一：直接安装资源包

如果您希望尽快装好并开始使用，最省事的方式是直接下载已经打包好的 `mcp-server.mcpb`：

- 最新下载地址：`https://github.com/AxT-Team/uapi-mcp/releases/latest/download/mcp-server.mcpb`
- 安装完成后，在资源包配置里填写 `uapikey`
- 如果后面需要管理员范围工具，再补 `UapiAdminBearerAuth`

这种方式不需要您自己手动构建，也不需要额外整理命令行参数。

### 方式二：从源码运行

如果您准备自己修改、调试或者二次打包，可以直接从源码运行。

#### 环境要求

- Node.js 18 或更高版本
- npm
- 首次构建会自动安装并使用 Bun

#### 安装依赖

```bash
npm install
```

#### 构建

```bash
npm run build
```

#### 启动本地 stdio 服务

如果客户端可以直接拉起本地 MCP 进程，建议这样启动：

```bash
node ./bin/mcp-server.js start --mode dynamic
```

#### 启动 Streamable HTTP 服务

如果客户端可以直接连接远程 MCP URL，建议这样启动：

```bash
node ./bin/mcp-server.js serve --mode dynamic --port 39002
```

启动后入口地址是：

```text
http://127.0.0.1:39002/mcp
```

#### 启动 SSE 服务

如果客户端仍然依赖 SSE，可以这样启动：

```bash
node ./bin/mcp-server.js start --transport sse --mode dynamic --port 39001
```

启动后可以访问：

- 首页：`http://127.0.0.1:39001/`
- SSE：`http://127.0.0.1:39001/sse`

## 客户端配置

### 通用本地配置

下面这份配置适合大多数可以本地拉起 MCP 进程的客户端。请把路径改成您自己的实际目录。

```json
{
  "mcpServers": {
    "Uapi Mcp": {
      "command": "node",
      "args": [
        "C:/path/to/uapi-mcp/bin/mcp-server.js",
        "start",
        "--mode",
        "dynamic"
      ],
      "env": {
        "UAPI_MCP_UAPIKEY": "YOUR_UAPI_KEY"
      }
    }
  }
}
```

### Codex 通过 HTTP 连接

如果您已经把服务跑在本机 `39002` 端口，可以这样配置：

```toml
[mcp_servers."Uapi Mcp"]
url = "http://127.0.0.1:39002/mcp"
http_headers = { "UapiKey" = "YOUR_UAPI_KEY" }
```

如果还需要管理员范围工具，再加上管理员 Token：

```toml
[mcp_servers."Uapi Mcp"]
url = "http://127.0.0.1:39002/mcp"
http_headers = { "UapiKey" = "YOUR_UAPI_KEY", "UapiAdminBearerAuth" = "YOUR_ADMIN_TOKEN" }
```

### MCP Bundle

如果您想安装资源包，可以先执行：

```bash
npm run mcpb:build
```

执行完成后会生成：

```text
./mcp-server.mcpb
```

这个包已经内置了 `user_config.uapikey`。安装时把自己的 Key 填进去即可。

## 配置项

### `uapikey`

`uapikey` 会用于所有上游请求，适合公开工具和日常使用场景。您可以通过下面几种方式配置：

- 命令行参数：`--uapikey YOUR_UAPI_KEY`
- 环境变量：`UAPI_MCP_UAPIKEY=YOUR_UAPI_KEY`
- HTTP 请求头：`UapiKey: YOUR_UAPI_KEY`
- MCP Bundle：`user_config.uapikey`

服务端会把它统一转换成上游的：

```text
Authorization: Bearer YOUR_UAPI_KEY
```

### `UapiAdminBearerAuth`

`UapiAdminBearerAuth` 只在管理员范围工具里需要。您可以通过下面几种方式配置：

- 命令行参数：`--uapi-admin-bearer-auth YOUR_ADMIN_TOKEN`
- 环境变量：`UAPI_MCP_UAPI_ADMIN_BEARER_AUTH=YOUR_ADMIN_TOKEN`
- HTTP 请求头：`UapiAdminBearerAuth: YOUR_ADMIN_TOKEN`

服务端同样会把它转换成上游的：

```text
Authorization: Bearer YOUR_ADMIN_TOKEN
```

如果 `uapikey` 和 `UapiAdminBearerAuth` 同时存在，管理员 Token 会优先生效。

## 运行模式

默认建议使用 `dynamic` 模式。这个模式不会在连接建立时一次性暴露全部业务工具，而是先提供 4 个元工具：

- `list_tools`
- `describe_tool_input`
- `execute_tool`
- `list_scopes`

对于工具数量比较多的服务，这种方式更省上下文，也更容易让模型按需调用。

## 常见问题

### 公开工具需要配什么

大多数情况下，只配 `uapikey` 就够用了。

### 访客额度用完怎么办

如果访客额度或免费积分用完了，可以先注册 `UapiPro`：`https://uapis.cn`。注册完成后，到 `UapiPro` 控制台创建 `UAPI Key`，再把这个 Key 填到 MCP 客户端或者资源包里的 `uapikey` 配置里，就可以继续使用。

### 管理员工具需要配什么

管理员范围工具需要额外传 `UapiAdminBearerAuth`。如果没有这个配置，服务端会直接返回可读的错误提示。

## 常用命令

查看 CLI 帮助：

```bash
node ./bin/mcp-server.js --help
```

只启动公开只读工具：

```bash
node ./bin/mcp-server.js serve --mode dynamic --scope read
```

只启动管理员工具：

```bash
node ./bin/mcp-server.js serve --mode dynamic --scope admin --uapi-admin-bearer-auth YOUR_ADMIN_TOKEN
```

运行回归检查：

```bash
npm run test:regression
```

打包 MCP Bundle：

```bash
npm run mcpb:build
```

## 文档

接口文档请查看 [uapis.cn](https://uapis.cn/docs)。

<!-- Start Summary [summary] -->
## Summary

For more information about the API: [UAPI 官方文档](https://uapis.cn/docs)
<!-- End Summary [summary] -->

<!-- Start Table of Contents [toc] -->
## Table of Contents
<!-- $toc-max-depth=2 -->
* [Uapi Mcp](#uapi-mcp)
  * [快速开始](#快速开始)
  * [客户端配置](#客户端配置)
  * [配置项](#配置项)
  * [运行模式](#运行模式)
  * [常见问题](#常见问题)
  * [常用命令](#常用命令)
  * [文档](#文档)
  * [Installation](#installation)
  * [Progressive Discovery](#progressive-discovery)

<!-- End Table of Contents [toc] -->

<!-- Start Installation [installation] -->
## Installation

> [!TIP]
> To finish publishing your MCP Server to npm and others you must [run your first generation action](https://www.speakeasy.com/docs/github-setup#step-by-step-guide).
<details>
<summary>Claude Desktop</summary>

Install the MCP server as a Desktop Extension using the pre-built [`mcp-server.mcpb`](./mcp-server.mcpb) file:

Simply drag and drop the [`mcp-server.mcpb`](./mcp-server.mcpb) file onto Claude Desktop to install the extension.

The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.

> [!NOTE]
> MCP bundles provide a streamlined way to package and distribute MCP servers. Learn more about [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).

</details>

<details>
<summary>Cursor</summary>

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=UapiMcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ1YXBpLW1jcCIsInN0YXJ0IiwiLS11YXBpLWFkbWluLWJlYXJlci1hdXRoIiwiIl19)

Or manually:

1. Open Cursor Settings
2. Select Tools and Integrations
3. Select New MCP Server
4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:

```json
{
  "command": "npx",
  "args": [
    "uapi-mcp",
    "start",
    "--uapi-admin-bearer-auth",
    ""
  ]
}
```

</details>

<details>
<summary>Claude Code CLI</summary>

```bash
claude mcp add UapiMcp -- npx -y uapi-mcp start --uapi-admin-bearer-auth 
```

</details>
<details>
<summary>Gemini</summary>

```bash
gemini mcp add UapiMcp -- npx -y uapi-mcp start --uapi-admin-bearer-auth 
```

</details>
<details>
<summary>Windsurf</summary>

Refer to [Official Windsurf documentation](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin) for latest information

1. Open Windsurf Settings
2. Select Cascade on left side menu
3. Click on `Manage MCPs`. (To Manage MCPs you should be signed in with a Windsurf Account)
4. Click on `View raw config` to open up the mcp configuration file.
5. If the configuration file is empty paste the full json

```bash
{
  "command": "npx",
  "args": [
    "uapi-mcp",
    "start",
    "--uapi-admin-bearer-auth",
    ""
  ]
}
```
</details>
<details>
<summary>VS Code</summary>

[![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20UapiMcp%20MCP&color=0098FF)](vscode://ms-vscode.vscode-mcp/install?name=UapiMcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ1YXBpLW1jcCIsInN0YXJ0IiwiLS11YXBpLWFkbWluLWJlYXJlci1hdXRoIiwiIl19)

Or manually:

Refer to [Official VS Code documentation](https://code.visualstudio.com/api/extension-guides/ai/mcp) for latest information

1. Open [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
1. Search and open `MCP: Open User Configuration`. This should open mcp.json file
2. If the configuration file is empty paste the full json

```bash
{
  "command": "npx",
  "args": [
    "uapi-mcp",
    "start",
    "--uapi-admin-bearer-auth",
    ""
  ]
}
```

</details>
<details>
<summary> Stdio installation via npm </summary>
To start the MCP server, run:

```bash
npx uapi-mcp start --uapi-admin-bearer-auth 
```

For a full list of server arguments, run:

```
npx uapi-mcp --help
```

</details>
<!-- End Installation [installation] -->

<!-- Start Progressive Discovery [dynamic-mode] -->
## Progressive Discovery

MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.

To enable dynamic mode, pass the `--mode dynamic` flag when starting your server:

```jsonc
{
  "mcpServers": {
    "UapiMcp": {
      "command": "npx",
      "args": ["uapi-mcp", "start", "--mode", "dynamic"],
      // ... other server arguments
    }
  }
}
```

In dynamic mode, the server registers only the following meta-tools instead of every individual tool:

- **`list_tools`**: Lists all available tools with their names and descriptions.
- **`describe_tool`**: Returns the input schema for one or more tools by name.
- **`execute_tool`**: Executes a tool by name with the provided input parameters.
- **`list_scopes`**: Lists the scopes available on the server.

This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.

You can combine dynamic mode with scope and tool filters:

```jsonc
{
  "mcpServers": {
    "UapiMcp": {
      "command": "npx",
      "args": ["uapi-mcp", "start", "--mode", "dynamic", "--scope", "admin"],
      // ... other server arguments
    }
  }
}
```
<!-- End Progressive Discovery [dynamic-mode] -->

<!-- Placeholder for Future Speakeasy SDK Sections -->