Summary
Routes file organization operations to Gemina's hosted endpoint. Exposes tag_file and tag_url tools that send PDFs or images up to 50 MB and return structured metadata, six filename patterns (date-first, vendor-first, compact, etc.), and a temporary download URL for the enriched file with embedded metadata. Outputs include extracted document type, vendor, date, amount, and tags. The server runs remotely at api.gemina.co, so there's no local daemon. Authentication uses X-API-Key headers. Useful when you need to programmatically rename receipts, invoices, or scanned documents without building your own OCR and classification pipeline. Free tier gives you 1,500 tags monthly with no card required.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Gemina FileTag — MCP server
Tag, rename, and enrich any PDF or image. One MCP call. Free tier: 1,500 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 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).
Output:
{
"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
-
Node.js 18+ — install from nodejs.org (Windows: ensure "Add to PATH" stays checked; macOS/Linux: standard installer).
-
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.comto the narrow allowlist — that's where signed enriched-file URLs are hosted).
Without network egress,
tag_file/tag_urlreturn 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": "<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--headerarg — it's the documented workaround fornpx's shell-split parsing. - The env-var indirection (
${GEMINA_API_KEY}) keeps the literal key out ofargs, 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 fromwhere npxin PowerShell (forward slashes work in JSON), e.g."C:/Program Files/nodejs/npx.cmd".
Cursor
File: ~/.cursor/mcp.json.
{
"mcpServers": {
"gemina": {
"url": "https://api.gemina.co/api/v1/mcp/",
"headers": {
"X-API-Key": "<paste-your-key-here>"
}
}
}
}
Claude Code (CLI)
claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \
--header "X-API-Key: <paste-your-key-here>"
VS Code
File: .vscode/mcp.json (per workspace).
{
"servers": {
"gemina": {
"type": "http",
"url": "https://api.gemina.co/api/v1/mcp/",
"headers": {
"X-API-Key": "<paste-your-key-here>"
}
}
}
}
Cline
In Cline's MCP settings (gear icon → MCP Servers → Edit Config), add:
{
"mcpServers": {
"gemina": {
"type": "streamableHttp",
"url": "https://api.gemina.co/api/v1/mcp/",
"headers": {
"X-API-Key": "<paste-your-key-here>"
}
}
}
}
Windsurf
File: ~/.codeium/windsurf/mcp_config.json. Note: the field is serverUrl, not url.
{
"mcpServers": {
"gemina": {
"serverUrl": "https://api.gemina.co/api/v1/mcp/",
"headers": {
"X-API-Key": "<paste-your-key-here>"
}
}
}
}
Codex CLI
Append to ~/.codex/config.toml:
[mcp_servers.gemina]
url = "https://api.gemina.co/api/v1/mcp/"
http_headers = { "X-API-Key" = "<paste-your-key-here>" }
OpenClaw
openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","headers":{"X-API-Key":"<paste-your-key-here>"}}'
Hermes-Agent
Append under mcp_servers in ~/.hermes/config.yaml:
mcp_servers:
gemina:
url: "https://api.gemina.co/api/v1/mcp/"
headers:
X-API-Key: "<paste-your-key-here>"
For the full machine-readable install guide (used by agents), see llms-install.md.
Free tier
1,500 tags per month. No credit card required. Sign up at 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.
Use cases
The same MCP call (tag_file or tag_url) powers all of these. Each example has a dedicated walkthrough in examples/.
| Use case | What it does | Example |
|---|---|---|
| 📥 Email attachment triage | Tag inbound attachments, route to folders by vendor/type | 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/langchain-loader |
| 🧾 Invoice automation | Extract vendor, totals, line items; route to AP; export to accounting | examples/bulk-tag-folder |
| 📁 Bulk document filing | Walk a directory, rename every file to a consistent pattern | examples/bulk-tag-folder |
| ⚡ Quickstart (curl) | First tag in three minutes, no MCP client needed | examples/curl-quickstart |
| 🖥️ Claude Desktop walkthrough | Step-by-step setup with screenshots | 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.
Documentation
- 📖 Full docs: gemina.co/docs/filetag — REST + MCP reference
- 🤖 Agent install guide:
llms-install.md— machine-readable, used by AI agents auto-discovering the server - 🔌 MCP manifest: gemina.co/.well-known/mcp.json
- 🏷️ REST endpoint reference: gemina.co/docs.md
Community & support
- 🐛 Bug reports
- 🆘 Integration help
- 💬 Discussions
- ✉️ Email: info@gemina.co
- 🔒 Security: see 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 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. 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.
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 and Privacy Policy.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →