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.

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

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

{
  "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)

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

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

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