jinero-mcp

# Jinero MCP Server

[![jinero-mcp MCP server](https://glama.ai/mcp/servers/jinero-online/jinero-mcp/badges/card.svg)](https://glama.ai/mcp/servers/jinero-online/jinero-mcp)

**`online.jinero/jinero`** — a hosted, remote [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents (Claude, Cursor, Cline, Zed, Gemini CLI…) the design tools of [jinero.online](https://jinero.online/dev/mcp?ref=github): **22 read-only tools** for fonts (search, CSS, files, recognition from an image), color math (WCAG contrast, shades, naming, palette extraction), curated palettes, code minify/convert/detect, SVG optimization and SCSS helpers.

- **Endpoint:** `https://jinero.online/mcp` (Streamable HTTP)
- **Auth:** none — anonymous & free, rate-limited at 60 req/min per IP (plus per-tool caps on heavy tools, see below)
- **Registry:** [`online.jinero/jinero`](https://registry.modelcontextprotocol.io/v0/servers?search=jinero) in the official MCP registry
- **Manifest:** [`/.well-known/mcp/server.json`](https://jinero.online/.well-known/mcp/server.json)
- **Human docs:** [jinero.online/dev/mcp](https://jinero.online/dev/mcp) — full reference with example responses

## Connect

**Claude Code (CLI):**

```bash
claude mcp add --transport http jinero https://jinero.online/mcp
```

**Claude Desktop / Cursor / Cline (config):**

```json
{
  "mcpServers": {
    "jinero": { "type": "http", "url": "https://jinero.online/mcp" }
  }
}
```

Older stdio-only clients can bridge with `npx mcp-remote https://jinero.online/mcp`.

## Trust & safety

Every tool declares MCP annotations, verifiable in `tools/list`:

- all 22 tools are **`readOnlyHint: true`** and **`idempotentHint: true`**;
- submitted code/SVG is parsed and transformed as text — **never executed, never stored**;
- uploaded images (font recognition, color extraction) are processed in memory and deleted immediately;
- only three tools fetch a user-supplied URL (`recognize_font`, `extract_colors`, `svg_to_datauri`) — marked `openWorldHint: true`, with SSRF-guarded, size-capped fetches.

> **A note for automated risk scanners:** some directories classify `minify_code`, `convert_code`, `generate_clamp` or `recognize_font` as "write" tools based on their verbs. They are pure functions — text/math in, text out; nothing on the server or the caller's side is modified. The authoritative signal is the `readOnlyHint: true` annotation each of the 22 tools declares in `tools/list` (snapshotted in [`tools.json`](tools.json)).

## Rate limits

The whole endpoint is capped at **60 requests/min per IP**. On top of that, compute-heavy tools enforce their own per-tool per-IP caps (server v1.4.0+), returned as a clean tool error with a retry hint when exceeded — each cap is also stated in the tool's description:

| Tool | Cap | Why |
|---|---|---|
| `recognize_font` | 5/min | CNN model inference |
| `extract_colors` | 10/min | image analysis subprocess |
| `minify_code`, `convert_code`, `optimize_svg` | 30/min | parser subprocesses |
| `svg_to_datauri` | 30/min | may fetch external URLs |

## Tests & CI

[`tests/tools.test.mjs`](tests/tools.test.mjs) exercises **every declared tool** against the live endpoint (zero dependencies, Node 20+):

```bash
npm test
```

CI runs the suite on every push and weekly ([workflow](.github/workflows/test.yml)), and [`tools.json`](tools.json) is a committed snapshot of the live `tools/list` — schemas and annotations included (`npm run update-snapshot` to refresh).

## Try it without a client

```bash
# List all tools
curl -s -X POST https://jinero.online/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

More runnable examples in [`examples/`](examples/).

## Tool reference

Generated from the live `tools/list` of the current server version.

### Fonts

#### `search_fonts`

Search the free font catalog by name, category, style tags, language coverage, variable/monospace flags and style count. Returns a paginated list of families.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `name` | string | Fuzzy name match. |
| `category` | string | Comma-separated categories, e.g. 'serif,sans'. |
| `langs` | string | Comma-separated language codes, e.g. 'latin,cyrillic' — ALL must be supported. |
| `style` | string | Comma-separated style tags, e.g. 'handwriting,condensed' — ALL must match. One of: handwriting, script, display, slab, rounded, condensed, expanded, stencil, pixel, blackletter, outline, retro. |
| `variable` | boolean | Only variable fonts. |
| `monospace` | boolean | Only monospace fonts. |
| `styles_min` | integer | Minimum number of styles. |
| `styles_max` | integer | Maximum number of styles. |
| `order` | string: likes \| downloads \| views \| name \| created_at | Sort field, default 'likes'. |
| `sort` | string: asc \| desc | Sort direction. |
| `per_page` | integer | Results per page (default 24). |
| `page` | integer | Page number. |

#### `recognize_font`

Identify which font is used in an image. Powered by our OWN CNN embedding model, trained on the jinero font catalog — it matches fonts by visual shape/style, so it needs NO OCR and NO text (works for Latin and Cyrillic). Send a tight crop of one line of text as either image_url (public URL) or image_base64 (base64/data-URI, e.g. a local screenshot). The image is processed in memory and deleted immediately — never stored. Returns the most visually similar font families with scores. Fast (~200 ms).

*read-only · idempotent · fetches external URLs*

| Parameter | Type | Description |
|---|---|---|
| `image_url` | string | Public URL of an image — a tight crop of one line of text. Provide either this or image_base64. Recognition is by visual shape (no OCR/text needed); Latin & Cyrillic supported. |
| `image_base64` | string | Base64-encoded image (raw base64 or a data:image/...;base64 URI), max 8 MB decoded — use this to send a local file/screenshot without hosting it. Provide either this or image_url. |
| `top_k` | integer | Number of font matches to return (3–20, default 8). |

#### `get_font`

Get full metadata for one font family by slug: styles, weights, axes, license, subsets and download/CSS URLs.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `slug` **(required)** | string | Family slug, e.g. 'inter', 'playfair-display'. |

#### `get_font_files`

List every font file (weight/italic/format + direct woff2/ttf URL) for a family — handy for building custom @font-face rules.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `slug` **(required)** | string | Family slug, e.g. 'inter'. |

#### `get_fonts_css`

Generate ready-to-use @font-face CSS for a family spec (Google-Fonts-compatible), e.g. "inter:wght@400,700" or a variable range "inter:wght@300..900". Returns CSS text.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `family` **(required)** | string | Family spec, e.g. "inter:wght@400,700" or "inter:wght@300..900". |
| `display` | string: swap \| auto \| block \| fallback \| optional | font-display value (default swap). |

#### `get_font_download_url`

Return the direct ZIP download URL for a font family (all styles + a ready fonts.css). Does NOT download — hand the URL to the user or fetch it separately.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `slug` **(required)** | string | Family slug, e.g. 'inter'. |

### Colors

#### `check_contrast`

Check the WCAG contrast ratio between a foreground and background color, with AA/AAA pass/fail for normal and large text.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `fg` **(required)** | string | Foreground color (hex, rgb(), or hsl()). |
| `bg` **(required)** | string | Background color (hex, rgb(), or hsl()). |

#### `get_color_shades`

Generate tints and shades for a base color (lighter/darker steps) with hex values.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `hex` **(required)** | string | Base color in hex, rgb(), or hsl(). |
| `step` | string: 5 \| 10 \| 20 \| 25 | Step percentage (default 10). |
| `limit` | integer | Cap on tints/shades (default fills to ~100%). |

#### `name_color`

Get the closest human-readable name for one or more colors. Pass a single hex or several comma-separated (e.g. "#3b82f6,#000,#ff7f50"); returns each input with its nearest color name, the reference hex, an exact-match flag and the perceptual distance.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `hex` **(required)** | string | A hex color, or several comma-separated (e.g. "#3b82f6,#000,#ff7f50"). Up to 100 at once. |

#### `extract_colors`

Extract a dominant-color palette from an image. Send either a public image_url or image_base64 (base64/data-URI, e.g. a local screenshot). The image is processed in memory and never stored. Each color comes back with its hex, rgb, hsl, share of the image, and the closest human color name — a named palette in one call.

*read-only · idempotent · fetches external URLs*

| Parameter | Type | Description |
|---|---|---|
| `image_url` | string | Public URL of the image to pull the palette from. Provide either this or image_base64. |
| `image_base64` | string | Base64-encoded image (raw base64 or a data:image/...;base64 URI), max 10 MB decoded — use this to send a local file/screenshot without hosting it. Provide either this or image_url. |
| `count` | integer | How many colors to return (2–16, default 8). |
| `mode` | string | Palette mode: "balanced" (default), "vibrant", or "muted". |

### Palettes

#### `search_palettes`

Search the color-palette catalog by name, tone, temperature, mood, harmony, exact color count and tags. Returns a paginated list.

*read-only · idempotent*

| Parameter | Type | Description |
|---|---|---|
| `name` | string | Fuzzy name match.