Uapi Mcp

Official MCP (Model Context Protocol) server for the 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):

https://uapis.cn/mcp

Local install (stdio, fully offline):

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.

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 for the full agent-facing playbook.

Related MCP server: IP Geolocation MCP Server

中文说明

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

安装依赖

npm install

构建

npm run build

启动本地 stdio 服务

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

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

启动 Streamable HTTP 服务

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

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

启动后入口地址是：

http://127.0.0.1:39002/mcp

启动 SSE 服务

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

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 进程的客户端。请把路径改成您自己的实际目录。

{
  "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 端口，可以这样配置：

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

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

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

MCP Bundle

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

npm run mcpb:build

执行完成后会生成：

./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

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

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

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

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 帮助：

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

只启动公开只读工具：

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

只启动管理员工具：

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

运行回归检查：

npm run test:regression

打包 MCP Bundle：

npm run mcpb:build

文档

接口文档请查看 uapis.cn。

Summary

For more information about the API: UAPI 官方文档

Table of Contents

• Uapi Mcp

  • 快速开始

  • 客户端配置

  • 配置项

  • 运行模式

  • 常见问题

  • 常用命令

  • 文档

  • Installation

  • Progressive Discovery

Installation

Install the MCP server as a Desktop Extension using the pre-built mcp-server.mcpb file:

Simply drag and drop the 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.

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:

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

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

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

Refer to Official Windsurf documentation 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

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

Or manually:

Refer to Official VS Code documentation for latest information

1. Open Command Palette

2. Search and open MCP: Open User Configuration. This should open mcp.json file

3. If the configuration file is empty paste the full json

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

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

For a full list of server arguments, run:

npx uapi-mcp --help

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:

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

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