> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Integrate Pictify with AI agents using Model Context Protocol

# MCP Server

Pictify provides an MCP (Model Context Protocol) server that enables AI agents to generate images, GIFs, and PDFs programmatically.

## What is MCP?

Model Context Protocol is a standard for connecting AI models to external tools and data sources. With Pictify's MCP server, AI assistants like Claude can:

* Generate images from descriptions
* Create social media graphics
* Render templates with dynamic data
* Capture screenshots of web pages

## Installation

### Claude Desktop

Add Pictify to your Claude Desktop configuration:

```json theme={null}
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "pictify": {
      "command": "npx",
      "args": ["-y", "@pictify/mcp-server"],
      "env": {
        "PICTIFY_API_KEY": "pk_live_your_api_key"
      }
    }
  }
}
```

Restart Claude Desktop after adding the configuration.

### Claude Code

```bash theme={null}
claude mcp add pictify -- npx -y @pictify/mcp-server
```

Set your API key:

```bash theme={null}
export PICTIFY_API_KEY=pk_live_your_api_key
```

### Other MCP Clients

The Pictify MCP server follows the standard MCP protocol and works with any compatible client.

## Available Tools

### `pictify_create_image`

Generate a static image from HTML, a URL screenshot, or a template. Provide exactly one of `html`, `url`, or `template`.

**Parameters:**

| Name            | Type   | Required | Description                                 |
| --------------- | ------ | -------- | ------------------------------------------- |
| `html`          | string | One of   | HTML/CSS content to render                  |
| `url`           | string | One of   | Public URL to screenshot                    |
| `template`      | string | One of   | Template UID (use with `variables`)         |
| `variables`     | object | No       | Template variables (when `template` is set) |
| `width`         | number | No       | Width in pixels, 1–4000 (default: 1200)     |
| `height`        | number | No       | Height in pixels, 1–4000 (default: 630)     |
| `selector`      | string | No       | CSS selector to capture a single element    |
| `fileExtension` | string | No       | `png` (default), `jpg`, `jpeg`, or `webp`   |

**Example:**

```
Create a social media card with the title "Hello World" on a purple gradient background, 1200x630 pixels.
```

The AI will call `pictify_create_image` with appropriate HTML. To screenshot a page, it passes `url` instead (optionally with `selector` to crop to a section).

### `pictify_render_template`

Render a saved template with variables.

**Parameters:**

| Name         | Type      | Required | Description                                           |
| ------------ | --------- | -------- | ----------------------------------------------------- |
| `templateId` | string    | Yes      | Template UID                                          |
| `variables`  | object    | No       | Template variables                                    |
| `format`     | string    | No       | `png` (default), `jpeg`, `webp`, or `pdf`             |
| `quality`    | number    | No       | Output quality 0.1–1.0 (JPEG/WebP only, default: 0.9) |
| `layout`     | string    | No       | Render a specific layout variant                      |
| `layouts`    | string\[] | No       | Render multiple layout variants in one call           |

**Example:**

```
Render my blog post template with title "AI in 2026" and author "Jane Smith".
```

### `pictify_create_gif`

Create an animated GIF from animated HTML, a URL, or a template. Provide exactly one of `html`, `url`, or `template`.

**Parameters:**

| Name        | Type   | Required | Description                                 |
| ----------- | ------ | -------- | ------------------------------------------- |
| `html`      | string | One of   | HTML with CSS `@keyframes`/transitions      |
| `url`       | string | One of   | URL to capture as a GIF                     |
| `template`  | string | One of   | Template UID (use with `variables`)         |
| `variables` | object | No       | Template variables (when `template` is set) |
| `width`     | number | No       | Width in pixels, 1–2000 (default: 800)      |
| `height`    | number | No       | Height in pixels, 1–2000 (default: 600)     |

<Note>
  To record a live web page over a fixed duration, use the `pictify_capture_gif` tool instead — it takes a `url` plus `frameDurationSeconds` (1–30) and a `quality` preset (`low` | `medium` | `high`).
</Note>

### `pictify_list_templates`

List available templates.

**Parameters:**

| Name           | Type   | Required | Description                                  |
| -------------- | ------ | -------- | -------------------------------------------- |
| `page`         | number | No       | Page number, starts at 1 (default: 1)        |
| `limit`        | number | No       | Templates per page, 1–100 (default: 12)      |
| `sort`         | string | No       | `newest` (default), `oldest`, or `name`      |
| `outputFormat` | string | No       | Filter by `all` (default), `image`, or `pdf` |

## Example Conversations

### Creating Social Graphics

**User:** Create a Twitter header image for my AI startup "NeuralFlow" with a dark theme and neural network visualization.

**Claude:** I'll create a Twitter header image for NeuralFlow with a dark neural network theme.

*Calls `pictify_create_image` with HTML for the header*

Here's your Twitter header image: \[Image URL]

The image features:

* Deep purple gradient background
* Animated neural network pattern
* "NeuralFlow" in modern typography
* Optimal 1500x500 dimensions for Twitter

### Rendering Templates

**User:** I have a blog post template. Generate images for these three posts:

1. "The Future of AI" by John Doe
2. "Web3 Explained" by Jane Smith
3. "Cloud Computing 101" by Bob Wilson

**Claude:** I'll render your blog post template for each article.

*Calls `pictify_render_template` three times with different variables*

Here are your blog post images:

1. "The Future of AI" - \[Image URL]
2. "Web3 Explained" - \[Image URL]
3. "Cloud Computing 101" - \[Image URL]

### Screenshots for Documentation

**User:** Take screenshots of our app's dashboard, settings page, and billing page for documentation.

**Claude:** I'll capture screenshots of each page for your documentation.

*Calls `pictify_create_image` with a `url` for each page*

Here are your documentation screenshots:

1. Dashboard - \[Image URL]
2. Settings - \[Image URL]
3. Billing - \[Image URL]

## Configuration Options

### Environment Variables

| Variable           | Description          | Default                  |
| ------------------ | -------------------- | ------------------------ |
| `PICTIFY_API_KEY`  | Your Pictify API key | Required                 |
| `PICTIFY_BASE_URL` | Custom API base URL  | `https://api.pictify.io` |

### Server Options

```json theme={null}
{
  "mcpServers": {
    "pictify": {
      "command": "npx",
      "args": ["-y", "@pictify/mcp-server"],
      "env": {
        "PICTIFY_API_KEY": "pk_live_...",
        "PICTIFY_BASE_URL": "https://api.pictify.io"
      }
    }
  }
}
```

## Building Custom Agents

### With Anthropic's Claude API

```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk';
import { Pictify } from '@pictify/sdk';

const anthropic = new Anthropic();
const pictify = new Pictify({ apiKey: process.env.PICTIFY_API_KEY! });

const tools = [
  {
    name: 'create_image',
    description: 'Generate an image from HTML content',
    input_schema: {
      type: 'object',
      properties: {
        html: { type: 'string', description: 'HTML content to render' },
        width: { type: 'number', description: 'Image width in pixels' },
        height: { type: 'number', description: 'Image height in pixels' }
      },
      required: ['html', 'width', 'height']
    }
  }
];

async function handleToolCall(name: string, input: any) {
  if (name === 'create_image') {
    const image = await pictify.renderHtml(input);
    return { url: image.url };
  }
}

async function chat(userMessage: string) {
  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    tools,
    messages: [{ role: 'user', content: userMessage }]
  });

  // Handle tool calls
  for (const block of response.content) {
    if (block.type === 'tool_use') {
      const result = await handleToolCall(block.name, block.input);
      // Continue conversation with tool result...
    }
  }
}
```

### With LangChain

```python theme={null}
from langchain.tools import Tool
from langchain.agents import initialize_agent
from pictify import Pictify

pictify = Pictify(api_key='pk_live_...')

def create_image(html: str, width: int = 1200, height: int = 630) -> str:
    """Generate an image from HTML content."""
    result = pictify.render_html(html=html, width=width, height=height)
    return result.url

tools = [
    Tool(
        name="create_image",
        func=create_image,
        description="Generate an image from HTML. Input should be HTML string."
    )
]

agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
```

## Best Practices

### 1. Provide Clear Descriptions

Give templates and tools clear descriptions so the AI understands when to use them:

```typescript theme={null}
{
  name: 'render_blog_card',
  description: 'Render a blog post social card. Use for creating Open Graph images for blog posts. Requires title, description, and author name.'
}
```

### 2. Handle Errors Gracefully

```typescript theme={null}
async function handleToolCall(name: string, input: any) {
  try {
    return await executeToolCall(name, input);
  } catch (error) {
    return {
      error: true,
      message: `Failed to ${name}: ${error.message}`
    };
  }
}
```

### 3. Validate Input

```typescript theme={null}
if (!input.html || !input.width || !input.height) {
  return { error: true, message: 'Missing required parameters' };
}

if (input.width > 4000 || input.height > 4000) {
  return { error: true, message: 'Dimensions exceed maximum (4000x4000)' };
}
```

### 4. Cache Results

For repeated requests, cache the results:

```typescript theme={null}
const cache = new Map();

async function createImage(options: RenderHtmlOptions) {
  const cacheKey = JSON.stringify(options);

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const result = await pictify.renderHtml(options);
  cache.set(cacheKey, result);
  return result;
}
```