Gemina

Gemina — MCP server

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

Install • Examples • Product page • Full docs

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 (ask questions and run spend analytics over your indexed documents — no re-upload). See 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

One sign-in, three tool groups. Every group takes any PDF or image up to 50 MB (PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF, AVIF).

1. FileTag — tag, rename, enrich (free tier). Send a document, get structured metadata, six suggested filenames, and a downloadable copy with the metadata embedded in the file itself. Tools: files_create_upload → tag_file, or tag_url.

2. Extraction — pull the fields out (paid). Ready-made models for invoice headers and invoice line items (plus Hebrew document details and line items); and custom templates — you define the fields, Gemina extracts them from any document type: contracts, forms, statements, delivery notes, IDs, anything. Tools: files_create_upload (purpose='extract') → extract_document → get_extraction_result, list_extractions, get_extraction, get_document, add_document_extractions (run more extraction types on a stored document — no re-upload; wait for the values, or wait=false and just file it for later search), submit_extraction_feedback (send corrections back).

3. Document Intelligence — ask your archive (paid). Ask questions and run spend analytics across your whole indexed collection — no re-upload. Every document you tag (FileTag) or run a structured extraction on is submitted for indexing when indexing is enabled — plain OCR isn't, and a document can be skipped (no extractable fields, or no indexing credits). Search by vendor, date, amount, type or free text (query_documents); get sums, averages and counts grouped by vendor, currency, type or month (aggregate_documents) — e.g. “total spent per vendor last quarter”. Tools: query_documents, aggregate_documents, index_document.

Sample: FileTag output (click to expand)

{

"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" }

Sample: extraction output (abridged — extract_document with invoice_headers )

{

"status": "success", "meta": { "extractionType": "invoice_headers", "modelType": "invictus", "extractionId": "…" }, "values": { "vendorName": { "value": "Acme Office Supplies Ltd.", "confidence": 0.98 }, "documentDate": { "value": "2026-02-15" }, "docNumber": { "value": "12345" }, "netAmount": { "value": 692.31 }, "vatAmount": { "value": 117.69 }, "totalAmount": { "value": 810.00 }, "currency": { "value": "USD" } }, "document": { "documentId": "…", "externalId": "your-idempotency-key" } }

With custom_template, values contains exactly the fields you defined in the template.

Sample: Document Intelligence (abridged — aggregate_documents )

{

"rows": [ { "group": { "vendor_name": "Acme Office Supplies Ltd.", "currency": "USD" }, "values": { "sum_total_amount": 810.0, "count": 1 } }, { "group": { "vendor_name": "BluePeak Cafe", "currency": "USD" }, "values": { "sum_total_amount": 26.19, "count": 1 } } ] }

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)

How OAuth sign-in works (click to expand)

• 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 (OAuth). See and revoke them under Console → API Keys → Connected apps at https://console.gemina.co.
• Most hosts need nothing beyond the URL. Three need an explicit second step — Codex CLI, OpenClaw and Hermes-Agent (see their sections) — and three can't sign in at all: Cline (no documented OAuth for remote servers as of 2026-08-27), curl and the OpenAI Responses API (no browser). ChatGPT is the mirror case: it signs in, but cannot send an API key.

Claude Desktop / claude.ai

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.

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 (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:

{

"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": " " } } } }

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".

Claude Code (CLI)

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

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):

claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \

--header "X-API-Key: "

Cursor

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):

{

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

API key (headless):

{

"mcpServers": { "gemina": { "url": "https://api.gemina.co/api/v1/mcp/", "headers": { "X-API-Key": " " } } } }

VS Code

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):

{

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

API key (headless):

{

"servers": { "gemina": { "type": "http", "url": "https://api.gemina.co/api/v1/mcp/", "headers": { "X-API-Key