# @air/mcp 中文文档

规范地址：https://npmcn.com/package/%40air/mcp/

版本：0\.1\.12
npm 元数据更新时间：2026-10-09T11:59:12.404Z
中文译文更新时间：2026-11-05T22:32:21.753Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40air/mcp
原文对照：https://npmcn.com/package/%40air/mcp/?lang=original
项目主页：https://github.com/AirLabsTeam/air-mcp#readme
源码仓库：https://github.com/AirLabsTeam/air-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：49.2 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：3 个
- 首次发布：2026-03-27T20:39:42.694Z
- 最新版本发布：2026-04-23T17:23:54.188Z
- 近 30 天下载量：11898（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Air.inc 平台的 MCP 服务器

## 安装

```sh
npm install @air/mcp
```

也可以使用：`pnpm add @air/mcp`、`yarn add @air/mcp`、`bun add @air/mcp`

## README

# @ air/ mcp (英语)

MCP 服务器 [空运](https://air.inc/) 平台。 将任何 MCP 兼容的 AI 客户端连接到您的 Air 工作空间, 允许进行资产搜索、 棋盘管理、 标记、 自定义字段等 .

支持两者 **科学、技术和科学司** (直接过程)和 **HTTP/SSE 软件** (本地主服务器) 传输.

## 先决条件

-   节点.js 18+
-   Air API 密钥和工作空间ID(从您的 [空气工作空间设置](https://app.air.inc/)(中文(简体) )

## 快开始

### 克劳德桌面

添加到您的 Claude 桌面配置( E)`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上:

```json
{
  "mcpServers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}
```

> **nvm 用户 :** Claude Desktop没有加载你的外壳配置文件,因此可能使用错误的节点版本. 如果您发现引擎出错, 请使用整个路径到一个节点 20+ `npx` 相反:
> 
> ```json
> "command": "/Users/you/.nvm/versions/node/v20.19.4/bin/npx"
> ```
> 
> 寻找你的路径 `nvm which 20` 在终端.

> 见 [Claude 桌面 MCP 文件](https://modelcontextprotocol.io/docs/develop/connect-local-servers) 更多细节.

### 克劳德代码

```bash
claude mcp add air -t stdio -e AIR_API_KEY=your-api-key -e AIR_WORKSPACE_ID=your-workspace-id -- npx -y @air/mcp
```

> 见 [Claude 代码 MCP 文件](https://docs.anthropic.com/en/docs/claude-code/mcp) 更多细节.

### 代码

添加到您的 Codex 配置( T)`~/.codex/config.toml`:

```toml
[mcp_servers.air]
command = "npx"
args = ["-y", "@air/mcp"]

[mcp_servers.air.env]
AIR_API_KEY = "your-api-key"
AIR_WORKSPACE_ID = "your-workspace-id"
```

或者通过CLI添加:

```bash
codex mcp add air --env AIR_API_KEY=your-api-key --env AIR_WORKSPACE_ID=your-workspace-id -- npx -y @air/mcp
```

> 见 [代码 MCP 文件](https://developers.openai.com/codex/mcp) 关于在 Codex 中配置 MCP 服务器的更详细信息.

### 光标

添加为 `.cursor/mcp.json` 在您的项目中或 `~/.cursor/mcp.json` 全球:

```json
{
  "mcpServers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}
```

> 见 [光标 MCP 文件](https://cursor.com/docs/context/mcp) 更多细节.

### 风起浪起

添加为 `~/.codeium/windsurf/mcp_config.json`数字 :

```json
{
  "mcpServers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}
```

> 见 [Windsurf MCP 文件](https://docs.windsurf.com/windsurf/cascade/mcp) 更多细节.

### VS 代码 (GitHub 副驾驶)

添加为 `.vscode/mcp.json` 在工程中,或者通过 **MCP: 打开用户配置** 命令 :

```json
{
  "servers": {
    "air": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}
```

> 确保使用副驾驶器 **代理模式** 访问 MCP 工具。 见 [VS 代码 MCP 文件](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 更多细节.

### 齐德

添加到您的 Zed 设置( E)`~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}
```

> 见 [Zed MCP 文档](https://zed.dev/docs/ai/mcp) 更多细节.

### ChatGPT 桌面 (HTTP/ SSE)

ChatGPT桌面不支持STDIO MCP服务器——它只通过HTTP支持MCP. 要连接到本地运行的 Air MCP 服务器 :

1.  克隆此还原,安装依赖,并创建 `.env` 文件(参见 `.env.example`:

```
AIR_API_KEY=your-api-key
AIR_WORKSPACE_ID=your-workspace-id
# AIR_API_URL=https://api.air.inc/v1  # optional, override for non-production environments
```

2.  启动 HTTP 服务器 :

```bash
npm run dev:http
```

3.  在 ChatGPT 中, 打开 **设置 – 连接器 – 添加连接器**。 。 。 .
4.  将 URL 设定为 :

```
http://localhost:3000/mcp
```

5.  设置认证到 **无** 并拯救我们.

> **说明:** ChatGPT MCP 支持需要 [开发者模式](https://platform.openai.com/docs/developer-mode) ,目前可通过Windows和网络获取. macOS 支持可能有限——见 [ChatGPT MCP 文档](https://developers.openai.com/api/docs/mcp) 这是最新消息.

## 可用工具

### 资产

| 工具 | 说明 |
| --- | --- |
| `list_assets` | 使用过滤器( 棋盘、 标签、 搜索、 自定义字段) 列出资产 |
| `list_nested_assets` | 在棋盘及其嵌入子棋盘中列出所有资产 |
| `get_asset` | 获取详细资产信息,包括封面版本和元数据 |
| `get_asset_download_url` | 获取资产版本的临时下载 URL |
| `get_asset_boards` | 列出所有含有资产的董事会 |
| `get_asset_image` | 获取资产内置图像预览( Base64) |
| `rename_asset` | 重命名资产的封面版本标题 |
| `update_asset` | 更新资产的显示标题和/或描述 |
| `add_tag_to_asset` | 在资产版本中添加标签 |
| `remove_tag_from_asset` | 从资产版本中删除标签 |
| `update_asset_custom_field` | 在资产上设置自定义字段值 |

### 董事会

| 工具 | 说明 |
| --- | --- |
| `list_boards` | 列表板,可选用名称或父过滤 |
| `get_board` | 获取详细的棋盘信息 |
| `create_board` | 创建新棋盘 |
| `update_board` | 更新棋盘的标题、描述或父目录 |
| `add_asset_to_board` | 将资产添加到棋盘中 |

### 标记

| 工具 | 说明 |
| --- | --- |
| `list_tags` | 列表标签, 可选用名称过滤 |
| `create_tag` | 创建新标签 |

### 自定义字段

| 工具 | 说明 |
| --- | --- |
| `list_custom_fields` | 列出工作空间中的自定义字段 |
| `get_custom_field` | 获取自定义字段细节,包括类型和可能的值 |

## 发展

```bash
# Clone and install
git clone https://github.com/AirInc/air-mcp.git
cd air-mcp
npm install

# Create .env with your credentials
cp .env.example .env

# Run in dev mode (STDIO)
npm run dev

# Run in dev mode (HTTP/SSE)
npm run dev:http

# Run unit tests
npm test

# Run end-to-end tests (requires AIR_API_KEY + AIR_WORKSPACE_ID in .env.test)
npm run test:e2e

# Typecheck
npm run typecheck

# Lint & format
npm run lint
npm run format

# Inspect with MCP Inspector
npm run inspect
```

## 常见问题

### @air/mcp 是什么？

Air\.inc 平台的 MCP 服务器

### 如何安装 @air/mcp？

在项目目录运行 npm install @air/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 air-mcp，可以用 npx air-mcp 直接运行。

### @air/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @air/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @air/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @air/mcp 可以商用吗？

@air/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @air/mcp 的下载量有多少？

根据 npm 官方下载统计，@air/mcp 在 2026/10/05 – 2026/11/03 这 30 天内被下载 11,898 次，日均约 397 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @air/mcp 还在维护吗？

最新版本 0\.1\.12 发布于 2026/04/24（6 个月前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。