gemina-mcp

<div align="center">
  <img src="assets/logo/logo.svg" alt="Gemina" width="120" />

# Gemina — MCP server

**Tag, extract, and search your documents from any MCP client. Free tier: 1,500 FileTag tags/month, no credit card.**

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Free tier](https://img.shields.io/badge/free%20tier-1%2C500%20tags%2Fmonth-brightgreen.svg)](https://www.gemina.co/filetag)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-purple.svg)](https://modelcontextprotocol.io)
[![Last commit](https://img.shields.io/github/last-commit/tommyil/gemina-mcp.svg)](https://github.com/tommyil/gemina-mcp/commits/main)

[Install](#quick-install) • [Examples](./examples) • [Product page](https://www.gemina.co/filetag) • [Full docs](https://www.gemina.co/docs/filetag)

</div>

---

## What is this?

This repository is the **discovery, install, and examples surface** for Gemina's MCP server. The server itself is hosted at `https://api.gemina.co/api/v1/mcp/` — there is no daemon to run locally. Point your MCP-compatible client at the endpoint, sign in with your Gemina account (or paste an API key for headless use), and tag your first document in under a minute.

One server, three tool groups: **FileTag** (free tier — tag, rename, and enrich any PDF or image), **Extraction** (Core-OCR: invoice headers, line items, full text, custom templates), and **Document Intelligence** (search and aggregate over your indexed documents). See [Tools](#tools) for the full list.

The server itself is closed-source (operated by Gemina). Everything in this repo — install snippets, examples, integration code — is MIT-licensed and contributions are welcome.

## What you get

Send a PDF or image. Get back structured metadata, six suggested filenames, and a downloadable copy with metadata already embedded in the file itself.

<details>
<summary><b>Sample input → sample output</b> (click to expand)</summary>

**Input:** any PDF or image up to 50 MB (PDF, PNG, JPEG, GIF, WebP, HEIC, AVIF).

**Output:**

```json
{
  "document_id": "abc-123",
  "suggested_filename": "2026-02-15_Acme-Corp_Invoice_12345.pdf",
  "metadata": {
    "document_type": "invoice",
    "vendor": "Acme Corp",
    "date": "2026-02-15",
    "amount": 7200,
    "currency": "ILS",
    "document_number": "12345",
    "title": "Invoice",
    "tags": ["vendor", "invoice"]
  },
  "filename_patterns": {
    "date_first": "2026-02-15_Invoice_12345.pdf",
    "type_first": "Invoice_12345_2026-02-15.pdf",
    "vendor_first": "Acme-Corp_Invoice_2026-02-15.pdf",
    "date_vendor": "2026-02-15_Acme-Corp.pdf",
    "vendor_date": "Acme-Corp_2026-02-15.pdf",
    "compact": "Acme-Corp_Invoice.pdf"
  },
  "enriched_file_url": "https://api.gemina.co/files/tmp_abc123.pdf",
  "enriched_file_expires_at": "2026-02-15T12:15:00Z"
}
```

Three uses out of one response — pick the one your code needs, ignore the rest.

</details>

## Quick install

**Sign in with your Gemina account** — no API key to copy. Every snippet below points your client at the endpoint; the client discovers Gemina's authorization server and opens a browser sign-in. Don't have an account? Create one free (no credit card) at **https://console.gemina.co/registration/create-account**.

Running headless (CI, servers, scripts, or a client that doesn't prompt to sign in)? Use the **API-key form** shown under each client instead.

**Endpoint:** `https://api.gemina.co/api/v1/mcp/` · **Transport:** Streamable HTTP · **Auth:** OAuth 2.1 sign-in (default) *or* `X-API-Key` header (headless)

<details>
<summary><b>How OAuth sign-in works</b> (click to expand)</summary>

- Clients discover the authorization server from the MCP URL via RFC 9728 (protected-resource metadata) and RFC 8414 (authorization-server metadata):
  - `https://api.gemina.co/.well-known/oauth-protected-resource/api/v1/mcp`
  - `https://api.gemina.co/.well-known/oauth-authorization-server/api/v1/mcp`
- Dynamic Client Registration (DCR) and Client ID Metadata Documents (CIMD) are both supported — no pre-registration, no client ID/secret to paste.
- Scope: `mcp`. Access tokens last 1 hour; refresh tokens rotate and last 30 days.
- Each connected app gets its own API key named `<app> (OAuth)`. See and revoke them under **Console → API Keys → Connected apps** at https://console.gemina.co.

</details>

<details>
<summary><b>Claude Desktop / claude.ai</b></summary>

**Recommended: OAuth via Connectors.** claude.ai and Claude Desktop use the same flow — no config file, no `mcp-remote`, no API key. Gemina creates a key for the app when you approve it.

```text
URL: https://api.gemina.co/api/v1/mcp/

1. Customize → Connectors
2. Add → Add custom connector
3. Paste the URL
4. Sign in
```

Sign in with your Gemina account when prompted and approve the consent page. The Gemina tools appear in new chats immediately.

**Fallback: API key via `mcp-remote`.** Claude Desktop's Connectors UI doesn't accept custom headers, so an API key has to go through the `mcp-remote` stdio bridge. Use this only if you need a specific key (headless or shared machines).

**Prerequisites**

1. **Node.js 18+** — install from [nodejs.org](https://nodejs.org/) (Windows: ensure "Add to PATH" stays checked; macOS/Linux: standard installer).
2. **Claude Desktop capabilities** — open **Settings → Capabilities** and turn on:
    - Code execution and file creation
    - Allow network egress
    - Domain allowlist: **All domains** (or add `storage.googleapis.com` to the narrow allowlist — that's where signed enriched-file URLs are hosted).

   Without network egress, `tag_file`/`tag_url` return JSON correctly but Claude can't fetch the enriched-file URL from storage and you'll see "Host not in allowlist". Settings only apply to **new** chats — start a fresh conversation after toggling.

**Config**

In Claude Desktop, **Settings → Developer → Edit Config** opens `claude_desktop_config.json` at:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Merge the `mcpServers` block alongside any existing config:

```json
{
  "mcpServers": {
    "gemina": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.gemina.co/api/v1/mcp/",
        "--header",
        "X-API-Key:${GEMINA_API_KEY}"
      ],
      "env": {
        "GEMINA_API_KEY": "<paste-your-key-here>"
      }
    }
  }
}
```

Save → fully quit Claude Desktop (Cmd+Q / right-click tray → Quit) → relaunch. First launch may take 10–30s while `npx` downloads `mcp-remote`.

**Notes**

- No space after `X-API-Key:` in the `--header` arg — it's the documented workaround for `npx`'s shell-split parsing.
- The env-var indirection (`${GEMINA_API_KEY}`) keeps the literal key out of `args`, where it could leak via process listings.
- **Windows + `spawn npx ENOENT`**: Claude Desktop doesn't inherit your shell's PATH. Replace `"command": "npx"` with the absolute path from `where npx` in PowerShell (forward slashes work in JSON), e.g. `"C:/Program Files/nodejs/npx.cmd"`.

</details>

<details>
<summary><b>Claude Code (CLI)</b></summary>

**OAuth (default):** register the server, then run `/mcp` and sign in — Claude Code opens the Gemina sign-in in your browser.

```bash
claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/
# then run /mcp and sign in
```

Inside Claude Code: `/mcp` → select **gemina** → **Authenticate** → sign in with your Gemina account in the browser → approve the consent page.

**API key (headless):**

```bash
claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \
  --header "X-API-Key: <paste-your-key-here>"
```

</details>

<details>
<summary><b>Cursor</b></summary>

File: `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). Cursor registers itself dynamically and opens your browser on the first 401 — no client ID or secret in the file.

**OAuth (default):**

```json
{
  "mcpServers": {
    "gemina": {
      "url": "https://api.gemina.co/api/v1/mcp/"
    }
  }
}
```

**API key (headless):**

```json
{
  "mcpServers": {
    "gemina": {
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

File: `.vscode/mcp.json` (per workspace), or run **MCP: Open User Configuration** from the Command Palette for all of them. VS Code registers dynamically and opens a browser on first connection; confirm the trust prompt, then find the account under **Accounts → Manage Trusted MCP Servers**.

**OAuth (default):**

```json
{
  "servers": {
    "gemina": {
      "type": "http",
      "url": "https://api.gemina.co/api/v1/mcp/"
    }
  }
}
```

**API key (headless):**

```json
{
  "servers": {
    "gemina": {
      "type": "http",
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

In Cline's MCP settings (gear icon → MCP Servers → Edit Config), add:

**OAuth (default):**

> **Cline is API-key only.** As of 2026-08-27 Cline has no documented OAuth path
> for remote MCP servers — its MCP docs never mention OAuth, and the one release
> note that does (v4.1.7) names the legacy SSE transport, not `streamableHttp`.
> Use the API-key form below.


**API key (headless):**

```json
{
  "mcpServers": {
    "gemina": {
      "type": "streamableHttp",
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

File: `~/.codeium/windsurf/mcp_config.json`, or the MCPs icon in the Cascade panel. Remote servers take `serverUrl` (`url` also works), then reload the MCP list. Now shipped as **Devin Desktop** — the Windsurf docs redirect there.

The docs say Ca