Uapi Mcp

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 官方文档

Installation

Tip

To finish publishing your MCP Server to npm and others you must run your first generation action.

Claude Desktop

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.

[!NOTE] MCP bundles provide a streamlined way to package and distribute MCP servers. Learn more about Desktop Extensions.

Cursor

Or manually:

Open Cursor Settings
Select Tools and Integrations
Select New MCP Server
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 Code CLI

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

Gemini

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

Windsurf

Refer to Official Windsurf documentation for latest information

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

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

VS Code

Or manually:

Refer to Official VS Code documentation for latest information

Open Command Palette
Search and open MCP: Open User Configuration. This should open mcp.json file
If the configuration file is empty paste the full json

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

Stdio installation via npm

To start the MCP server, run:

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

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
.speakeasy		.speakeasy
scripts		scripts
src		src
.dxtignore		.dxtignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
banner.png		banner.png
eslint.config.mjs		eslint.config.mjs
manifest.json		manifest.json
openapi.yaml		openapi.yaml
overlay.yaml		overlay.yaml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Uapi Mcp

快速开始

方式一：直接安装资源包

方式二：从源码运行

环境要求

安装依赖

构建

启动本地 stdio 服务

启动 Streamable HTTP 服务

启动 SSE 服务

客户端配置

通用本地配置

Codex 通过 HTTP 连接

MCP Bundle

配置项

`uapikey`

`UapiAdminBearerAuth`

运行模式

常见问题

公开工具需要配什么

访客额度用完怎么办

管理员工具需要配什么

常用命令

文档

Summary

Table of Contents

Installation

Progressive Discovery

About

Uh oh!

Releases 3

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Uapi Mcp

快速开始

方式一：直接安装资源包

方式二：从源码运行

环境要求

安装依赖

构建

启动本地 stdio 服务

启动 Streamable HTTP 服务

启动 SSE 服务

客户端配置

通用本地配置

Codex 通过 HTTP 连接

MCP Bundle

配置项

uapikey

UapiAdminBearerAuth

运行模式

常见问题

公开工具需要配什么

访客额度用完怎么办

管理员工具需要配什么

常用命令

文档

Summary

Table of Contents

Installation

Progressive Discovery

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`uapikey`

`UapiAdminBearerAuth`

Packages