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_KEYUapiAdminBearerAuth
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_toolsdescribe_tool_inputexecute_toollist_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
* 快速开始 * 客户端配置 * 配置项 * 运行模式 * 常见问题 * 常用命令 * 文档 * Installation * Progressive Discovery
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 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 configto 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 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 --helpProgressive 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
}
}
}