# Gemina FileTag [Health: Active] **Category:** ๐Ÿ’ป Developer Tools **Repository:** https://github.com/tommyil/gemina-mcp **GitHub Stars:** 1 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/gemina-filetag ## Description Tag, rename, and enrich PDFs and images. Free tier: 1,500 tags/month, no credit card. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "gemina-filetag": { "command": "npx", "args": ["-y","ENOENT"] } } ``` ## Documentation & README
Gemina # Gemina FileTag โ€” MCP server **Tag, rename, and enrich any PDF or image. One MCP call. Free tier: 1,500 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)
--- ## What is this? This repository is the **discovery, install, and examples surface** for Gemina FileTag'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, paste an API key, and tag your first document in under a minute. 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.
Sample input โ†’ sample output (click to expand) **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.
## Quick install You need an API key. Get one free (no credit card) at **https://console.gemina.co/registration/create-account**, then drop the snippet below into your MCP client's config and restart it. **Endpoint:** `https://api.gemina.co/api/v1/mcp/` ยท **Transport:** Streamable HTTP ยท **Auth:** `X-API-Key` header
Claude Desktop Claude Desktop's Custom Connectors UI (**Customize โ†’ Connectors**) only supports OAuth and doesn't accept custom headers โ€” it can't authenticate against Gemina's `X-API-Key`. Use the `mcp-remote` stdio bridge instead. **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": "" } } } } ``` 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"`.
Cursor File: `~/.cursor/mcp.json`. ```json { "mcpServers": { "gemina": { "url": "https://api.gemina.co/api/v1/mcp/", "headers": { "X-API-Key": "" } } } } ```
Claude Code (CLI) ```bash claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \ --header "X-API-Key: " ```
VS Code File: `.vscode/mcp.json` (per workspace). ```json { "servers": { "gemina": { "type": "http", "url": "https://api.gemina.co/api/v1/mcp/", "headers": { "X-API-Key": "" } } } } ```
Cline In Cline's MCP settings (gear icon โ†’ MCP Servers โ†’ Edit Config), add: ```json { "mcpServers": { "gemina": { "type": "streamableHttp", "url": "https://api.gemina.co/api/v1/mcp/", "headers": { "X-API-Key": "" } } } } ```
Windsurf File: `~/.codeium/windsurf/mcp_config.json`. Note: the field is `serverUrl`, not `url`. ```json { "mcpServers": { "gemina": { "serverUrl": "https://api.gemina.co/api/v1/mcp/", "headers": { "X-API-Key": "" } } } } ```
Codex CLI Append to `~/.codex/config.toml`: ```toml [mcp_servers.gemina] url = "https://api.gemina.co/api/v1/mcp/" http_headers = { "X-API-Key" = "" } ```
OpenClaw ```bash openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","headers":{"X-API-Key":""}}' ```
Hermes-Agent Append under `mcp_servers` in `~/.hermes/config.yaml`: ```yaml mcp_servers: gemina: url: "https://api.gemina.co/api/v1/mcp/" headers: X-API-Key: "" ```
For the full machine-readable install guide (used by agents), see [`llms-install.md`](./llms-install.md). ## Free tier **1,500 tags per month. No credit card required.** Sign up at [gemina.co/filetag](https://www.gemina.co/filetag), grab an API key, paste it into your config. The same key works for both MCP and the REST API. Need more? Paid plans add larger monthly allowances, configurable data residency, and longer retention. See [pricing](https://www.gemina.co/pricing). ## Use cases The same MCP call (`tag_file` or `tag_url`) powers all of these. Each example has a dedicated walkthrough in [`examples/`](./examples). | Use case | What it does | Example | |---|---|---| | ๐Ÿ“ฅ **Email attachment triage** | Tag inbound attachments, route to folders by vendor/type | [`examples/gmail-attachment-triage`](./examples/gmail-attachment-triage) | | ๐Ÿ” **RAG ingestion** | Attach structured metadata to vector store entries so retrieval can filter by vendor, date, or document type | [`examples/llamaindex-reader`](./examples/llamaindex-reader) ยท [`examples/langchain-loader`](./examples/langchain-loader) | | ๐Ÿงพ **Invoice automation** | Extract vendor, totals, line items; route to AP; export to accounting | [`examples/bulk-tag-folder`](./examples/bulk-tag-folder) | | ๐Ÿ“ **Bulk document filing** | Walk a directory, rename every file to a consistent pattern | [`examples/bulk-tag-folder`](./examples/bulk-tag-folder) | | โšก **Quickstart (curl)** | First tag in three minutes, no MCP client needed | [`examples/curl-quickstart`](./examples/curl-quickstart) | | ๐Ÿ–ฅ๏ธ **Claude Desktop walkthrough** | Step-by-step setup with screenshots | [`examples/claude-desktop`](./examples/claude-desktop) | ## Why FileTag, not a raw LLM call? A naive "ask GPT to tag this PDF" pipeline breaks in production: hallucinated vendor names, inconsistent date formats, no structured output, no PDF metadata embedding, no enriched-file roundtrip. FileTag is the harness around that call โ€” specialized agents that **reason, cross-check, and refuse to guess** โ€” wrapped in a single endpoint with a stable JSON contract. | | Raw LLM | Gemina FileTag | |---|---|---| | Structured output | Free text, requires parsing | Stable JSON schema | | Filename suggestions | None | Six patterns, ready to use | | PDF metadata embedding | DIY | Returned as downloadable enriched copy | | Hallucinations | Frequent | Cross-checked, refuses when unsure | | Per-document cost | $$ per call | Free for first 1,500/month | ## Privacy & trust - **No model training.** Your documents are never used to train AI models โ€” Gemina's or anyone else's. - **7-day deletion.** Files are deleted within 7 days of upload (configurable per plan). - **Encryption.** AES-256 at rest, TLS 1.3 in transit. - **Compliance.** GDPR and CCPA compliant. Configurable data residency on paid plans. Full details on the [Gemina Trust Center](https://www.gemina.co/trust-center). ## Documentation - ๐Ÿ“– **Full docs:** [gemina.co/docs/filetag](https://www.gemina.co/docs/filetag) โ€” REST + MCP reference - ๐Ÿค– **Agent install guide:** [`llms-install.md`](./llms-install.md) โ€” machine-readable, used by AI agents auto-discovering the server - ๐Ÿ”Œ **MCP manifest:** [gemina.co/.well-known/mcp.json](https://www.gemina.co/.well-known/mcp.json) - ๐Ÿท๏ธ **REST endpoint reference:** [gemina.co/docs.md](https://www.gemina.co/docs.md) ## Community & support - ๐Ÿ› [Bug reports](https://github.com/tommyil/gemina-mcp/issues/new?template=bug.yml) - ๐Ÿ†˜ [Integration help](https://github.com/tommyil/gemina-mcp/issues/new?template=integration_help.yml) - ๐Ÿ’ฌ [Discussions](https://github.com/tommyil/gemina-mcp/discussions) - โœ‰๏ธ Email: [info@gemina.co](mailto:info@gemina.co) - ๐Ÿ”’ Security: see [SECURITY.md](./SECURITY.md) ## For aggregators and directory listings The `Dockerfile` at the repo root is **not for end users.** It exists so directory operators (e.g. Glama's `/mcp/servers/` tier) can build a container that introspects the public tool surface without provisioning credentials. The container runs [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) against `https://api.gemina.co/api/v1/mcp/public/` โ€” a read-only discovery endpoint that serves `initialize` / `tools/list` / `prompts/list` to anonymous callers but refuses `tools/call`. End users should follow the **Quick install** section above and connect to the authenticated endpoint with their personal API key. ## Contributing Examples PRs welcome โ€” see [CONTRIBUTING.md](./CONTRIBUTING.md). The server itself is closed-source, so PRs that touch the actual MCP server logic will be declined, but bug reports against the live server are very welcome. ## License The contents of this repository โ€” install snippets, example code, documentation, configuration files, and sample assets โ€” are released under the [MIT License](./LICENSE). The Gemina FileTag MCP server itself is a hosted closed-source service operated by Gemina (https://gemina.co) and is **not** covered by this license. Use of the server is governed by [Gemina's Terms of Service](https://www.gemina.co/terms-of-service) and [Privacy Policy](https://www.gemina.co/privacy-policy).