@titlize/mcp-connector

MCP (Model Context Protocol) server for the Image Titler API. Enables AI assistants like Claude Code and Cursor to generate Open Graph images and check usage quotas via natural language.

Prerequisites

• Node.js 22+
• An Image Titler API token (create one at the dashboard)
• An AI assistant that supports MCP (Claude Code, Cursor, etc.)

Installation

Option 1: npx (zero install)

No installation needed -- runs directly:

npx @titlize/mcp-connector

Option 2: Global install

npm install -g @titlize/mcp-connector

Configuration

Claude Code

claude mcp add --transport stdio image-titler \
  --env IMAGE_TITLER_API_TOKEN=your-token-here \
  --env IMAGE_TITLER_BASE_URL=https://your-api-url.com \
  -- npx -y @titlize/mcp-connector

Or manually edit ~/.claude.json:

{
  "mcpServers": {
    "image-titler": {
      "command": "npx",
      "args": ["-y", "@titlize/mcp-connector"],
      "env": {
        "IMAGE_TITLER_API_TOKEN": "your-token-here",
        "IMAGE_TITLER_BASE_URL": "https://your-api-url.com"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | IMAGE_TITLER_API_TOKEN | Yes | Your API token from the dashboard | | IMAGE_TITLER_BASE_URL | Yes | API base URL (e.g., https://your-api.com) |

CLI Arguments (override env vars)

npx @titlize/mcp-connector --api-token=your-token --base-url=https://your-api.com

Available Tools

| Tool | Description | |------|-------------| | generate_image | Generate an OG image with text overlay on a source image | | check_usage | Check current usage count and remaining quota |

generate_image

Generates a social media preview image by overlaying text on a source image.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | Yes | Main text to overlay on the image | | image_url | string | Yes | URL or local path to the source image | | subtitle | string | No | Secondary text below the title |

check_usage

Returns the current month's usage count and remaining quota for your API token.

No parameters required.

Usage Examples

Once configured, ask your AI assistant:

"Generate an OG image for my blog post 'Getting Started with MCP' using the image at ./hero.jpg"

"Create a social image with the title 'Launch Day!' and subtitle 'Version 2.0 is here' from https://example.com/photo.png"

"Check my Image Titler usage for this month"

Troubleshooting

"API token is required": Set IMAGE_TITLER_API_TOKEN in your MCP config env.

"Base URL is required": Set IMAGE_TITLER_BASE_URL in your MCP config env.

"Authentication failed": Your API token may be invalid or expired. Create a new one at the dashboard.

"Cannot reach API": Check that IMAGE_TITLER_BASE_URL is correct and the API is running.

Transport errors: This server uses stdio transport. Ensure your MCP client is configured for stdio (not HTTP).

stdout pollution: The MCP connector reserves stdout for JSON-RPC communication. All logging uses console.error(). If you see protocol errors, check that no other code writes to stdout.

Development

# Install dependencies
pnpm install

# Build (TypeScript -> JavaScript)
pnpm build

# Type check without emitting
pnpm typecheck

# Run linter
pnpm lint
pnpm lint:fix

# Run all tests
pnpm test

# Run unit tests only
pnpm test:unit

# Run tests with coverage
pnpm test:coverage

# Watch mode during development
pnpm dev

Testing

Tests use Vitest (not Jest). Test files follow the convention:

• Unit tests: tests/unit/**/*.unit.test.ts
• Integration tests: tests/integration/**/*.integration.test.ts

License

Private