@air/mcp

中文文档

0.1.12发布于 2026/04/24MITTypeScriptES Module近 30 天下载 1.2万

MCP server for the Air.inc platform

文档目录16 节

Prerequisites
Quick start
Claude Desktop
Claude Code
Codex
Cursor
Windsurf
VS Code (GitHub Copilot)
Zed
ChatGPT Desktop (HTTP/SSE)
Available tools
Assets
Boards
Tags
Custom fields
Development

@air/mcp

MCP server for the Air platform. Connects any MCP-compatible AI client to your Air workspace, enabling asset search, board management, tagging, custom fields, and more.

Supports both STDIO (direct process) and HTTP/SSE (localhost server) transports.

Prerequisites

Node.js 18+
An Air API key and workspace ID (get these from your Air workspace settings)

Quick start

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

nvm users: Claude Desktop doesn't load your shell profile, so it may use the wrong Node version. If you get engine errors, use the full path to a Node 20+ npx instead:
"command": "/Users/you/.nvm/versions/node/v20.19.4/bin/npx"
Find your path with nvm which 20 in a terminal.

See Claude Desktop MCP docs for more details.

Claude Code

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

See Claude Code MCP docs for more details.

Codex

Add to your Codex config (~/.codex/config.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"

Or add via the CLI:

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

See Codex MCP docs for more details on configuring MCP servers in Codex.

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

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

See Cursor MCP docs for more details.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

See Windsurf MCP docs for more details.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project, or open the user-level config via the MCP: Open User Configuration command:

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

Make sure to use Copilot in Agent mode to access MCP tools. See VS Code MCP docs for more details.

Zed

Add to your Zed settings (~/.config/zed/settings.json):

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

See Zed MCP docs for more details.

ChatGPT Desktop (HTTP/SSE)

ChatGPT desktop does not support STDIO MCP servers — it only supports MCP via HTTP. To connect it to a locally running Air MCP server:

Clone this repo, install dependencies, and create a .env file (see .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

Start the HTTP server:

npm run dev:http

In ChatGPT, open Settings → Connectors → Add connector.
Set the URL to:

http://localhost:3000/mcp

Set authentication to None and save.

Note: ChatGPT MCP support requires Developer mode and is currently available on Windows and web. macOS support may be limited — see ChatGPT MCP docs for the latest.

Available tools

Assets

Tool	Description
`list_assets`	List assets with filters (board, tags, search, custom fields)
`list_nested_assets`	List all assets within a board and its nested sub-boards
`get_asset`	Get detailed asset info including cover version and metadata
`get_asset_download_url`	Get a temporary download URL for an asset version
`get_asset_boards`	List all boards that contain an asset
`get_asset_image`	Get an inline image preview (base64) of an asset
`rename_asset`	Rename an asset's cover version title
`update_asset`	Update an asset's display title and/or description
`add_tag_to_asset`	Add a tag to an asset version
`remove_tag_from_asset`	Remove a tag from an asset version
`update_asset_custom_field`	Set a custom field value on an asset

Boards

Tool	Description
`list_boards`	List boards, optionally filtered by name or parent
`get_board`	Get detailed board info
`create_board`	Create a new board
`update_board`	Update a board's title, description, or parent
`add_asset_to_board`	Add assets to a board

Tool	Description
`list_tags`	List tags, optionally filtered by name
`create_tag`	Create a new tag

Custom fields

Tool	Description
`list_custom_fields`	List custom fields in the workspace
`get_custom_field`	Get custom field details including type and possible values

Development

# 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 共发布 12 个版本，首次发布于 2026/03/28；过去 12 个月发布了 12 个版本。

版本	发布日期	距今
`0.1.12`latest	2026/04/24	6 个月前
`0.1.11`	2026/04/11	6 个月前
`0.1.10`	2026/04/11	6 个月前
`0.1.9`	2026/04/04	7 个月前
`0.1.8`	2026/04/04	7 个月前
`0.1.7`	2026/03/29	7 个月前

关于 @air/mcp 的常见问题

@air/mcp 是什么？

MCP server for the Air.inc platform

如何安装 @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 和提交记录判断。

npm install @air/mcp

pnpmpnpm add @air/mcp
yarnyarn add @air/mcp
bunbun add @air/mcp

命令行npx air-mcp

在你的项目目录中运行此命令。

近 30 天下载

11,898

约 1.2万次日均 397 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，2 天前更新

最新版本0.1.12发布于 6 个月前

开源许可MIT宽松许可

包体积49.2 kB5 个文件 · 解压后

运行依赖3 个

模块格式ES Module

TypeScript自带类型

Node.js>=18

发布版本12 个近 12 个月 12 个

首次发布2026/03/287 个月前

元数据更新2026/10/09

每一个软件包背后，
都有分享与创造的人。

@air/mcp

@air/mcp

Prerequisites

Quick start

Claude Desktop

Claude Code

Codex

Cursor

Windsurf

VS Code (GitHub Copilot)

Zed

ChatGPT Desktop (HTTP/SSE)

Available tools

Assets

Boards

Tags

Custom fields

Development

版本与发布记录

关于 @air/mcp 的常见问题

@air/mcp 是什么？

如何安装 @air/mcp？

@air/mcp 支持 TypeScript 吗？

@air/mcp 支持 ESM 还是 CommonJS？

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

@air/mcp 可以商用吗？

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

@air/mcp 还在维护吗？