# memeport

Need a meme, not a design project? memeport searches a
catalogue of more than 25,000 meme templates hosted by
Memeboat, lets you inspect a template before you commit to
it, and captions it for you — returning the finished meme's
page URL and its direct image URL, ready to share.

Captions follow the template's own boxes. One caption lands
at the bottom, two become top and bottom, and any more fill
the template's caption boxes in order. Each caption can be a
plain string, or an object that styles just that caption:
its text, a `color`, an `outline`, and a `font`. A top-level
`font` sets the default for every caption, and
`layout: "top"` moves the captions into a white bar above
the image instead of overlaying them on the picture.

Colours are a hex value (`#rgb` or `#rrggbb`) or one of
`white`, `black`, `red`, `yellow`, `blue`, `green`. Fonts
are `impact`, `arial`, `helvetica`, `times`, `courier`,
`titillium`, `thick`, `kalam`, `comic`, `notosans`, and
`notosanshebrew`.

## Configuration

No account and no API key: the Memeboat API is free and
anonymous.

```bash
export MEMEBOAT_API_URL="https://memebo.at"   # optional override
```

Leave `MEMEBOAT_API_URL` unset to use the public instance
at `https://memebo.at`.

## CLI

Each subcommand takes a single JSON argument string:

```bash
npx @reneturcios/memeport search_meme_templates '{"query":"drake","limit":5}'
npx @reneturcios/memeport get_meme_template '{"slug":"drake-hotline-bling"}'
npx @reneturcios/memeport create_meme '{"template":"drake-hotline-bling","texts":["no","yes"]}'
npx @reneturcios/memeport create_meme '{"template":"two-buttons","texts":[{"text":"one","color":"#fff","font":"impact"}],"font":"arial","layout":"top"}'
npx @reneturcios/memeport --version
```

Output is the upstream payload as JSON. Exit codes: `0` on
success, `1` on a runtime error (including a validation
error or a non-2xx upstream response), `2` on a usage
error.

## MCP server

```bash
npx -y @reneturcios/memeport mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "memeport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/memeport", "mcp"]
    }
  }
}
```

### Tools

- `search_meme_templates` — Search meme templates by name
  or topic. Returns slugs, image URLs and a
  suggestedCaptionCount per template. Arguments: `query`
  (required), `limit` (optional).
- `get_meme_template` — Get details for one meme template
  by slug: dimensions, image URL and caption count.
  Arguments: `slug` (required).
- `create_meme` — Caption a meme template and get back
  the meme's page URL and direct image URL. Arguments:
  `template` and `texts` (required), `font` and `layout`
  (optional).

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/memeport
docker run --rm ghcr.io/cloudcorprecords/memeport search_meme_templates '{"query":"cat"}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios