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

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

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

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

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

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 — check OpenAI's 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 | | 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 | | 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 tests
npm test

# Typecheck
npm run typecheck

# Lint & format
npm run lint
npm run format

# Inspect with MCP Inspector
npm run inspect