ctx.st / images / mcp

Connect AI agents (Claude Code, Claude Desktop, etc.) to your image hosting via the MCP protocol.

1. Create an API Key

Log into i.ctx.st and click api keys in the header. Create a key with a descriptive name (e.g. "claude-code").

Copy the key — it starts with ik_ and is shown only once.

2. Install Dependencies

cd /path/to/apps/images/mcp
npm install

The MCP server has its own package.json — dependencies must be installed before first use.

3. Configure MCP Server

Claude Code — add to your project's .mcp.json:

{
  "mcpServers": {
    "images": {
      "command": "node",
      "args": ["/path/to/apps/images/mcp/index.js"],
      "env": {
        "IMAGES_API_KEY": "ik_your_key_here"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "images": {
      "command": "node",
      "args": ["/path/to/apps/images/mcp/index.js"],
      "env": {
        "IMAGES_API_KEY": "ik_your_key_here"
      }
    }
  }
}

Replace /path/to/ with the actual path to the repository on your machine.

4. Available Tools

• images_upload — Upload from local file or URL, with optional description/tags
• images_list — List images with optional search/filter
• images_search — Search images by description or tags
• images_get — Get metadata + URL for a single image
• images_delete — Delete an image
• images_describe — AI-generate description, tags, and alt text
• images_stats — Storage statistics

5. Example Usage

# Upload a screenshot
> Upload ~/Desktop/metrics.png with description "Q1 dashboard"

# Search your images
> Find my dashboard screenshots

# AI describe
> What's in image k7Xm2pQ1?

6. Direct API Access

You can also use the REST API directly with your API key:

curl -H "Authorization: Bearer ik_your_key" \
     https://i.ctx.st/api/images

All API endpoints accept Bearer ik_xxx authentication.