aperture-mcp

MCP (Model Context Protocol) server for Aperture, an open-source digital asset manager. This server exposes Aperture assets, tags, folders, and brand kits as tools that AI assistants like Claude can use.

Installation

Install globally:

npm install -g aperture-mcp

Or run directly with npx (no install required):

npx aperture-mcp

Environment Variables

| Variable | Required | Description | |---|---|---| | APERTURE_API_URL | Yes | Base URL of your Aperture instance (e.g. https://your-aperture-instance.com) | | APERTURE_API_KEY | Yes | API key for authentication (e.g. apt_your_api_key_here) |

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aperture": {
      "command": "npx",
      "args": ["aperture-mcp"],
      "env": {
        "APERTURE_API_URL": "https://your-aperture-instance.com",
        "APERTURE_API_KEY": "apt_your_api_key_here"
      }
    }
  }
}

Available Tools

search_assets

Search or browse assets in Aperture. Supports text search, tag filtering, folder filtering, and type filtering.

Parameters:

• query (string, optional) - Text search query
• tags (string[], optional) - Filter by tag names
• folder (string, optional) - Filter by folder ID
• type (string, optional) - Filter by asset type (image, video, document, etc.)

get_asset

Get detailed information about a specific asset including tags, folder path, dimensions, and brand kit association.

Parameters:

• id (string, required) - The asset ID

list_tags

List all tags in Aperture with their associated asset counts.

Parameters: None

list_categories

List all folders (categories) as a hierarchical tree structure.

Parameters: None

get_brand_kit

Retrieve a brand kit by ID or name. Returns brand colors, typography, spacing, tone guidelines, and component definitions.

Parameters:

• id (string, optional) - The brand kit ID
• name (string, optional) - The brand kit name (used to look up the ID if id is not provided)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT