@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:

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

2. Start the HTTP server:

npm run dev:http

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

http://localhost:3000/mcp

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

Tags

| 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