{
  "markdown": "# clichefactory-mcp\n\n<!-- mcp-name: io.github.ClicheFactory/clichefactory-mcp -->\n\nMCP (Model Context Protocol) server for [ClicheFactory](https://clichefactory.com) — structured data extraction from documents.\n\nThis server exposes ClicheFactory's extraction and document conversion capabilities as MCP tools, allowing AI assistants in Cursor, Claude Desktop, OpenClaw, and other MCP-compatible clients to extract structured data from PDFs, images, DOCX, XLSX, CSV, EML, and more.\n\n## Quick start (recommended — service mode)\n\nService mode uses the ClicheFactory cloud for the best extraction quality. You only need one API key.\n\n1. **Sign up** at [clichefactory.com](https://clichefactory.com) — free pages included, no credit card required.\n2. **Create an API key** in [Settings → API Keys](https://clichefactory.com) (format: `cliche-...`).\n3. **Install** the MCP server:\n\n   ```bash\n   pip install clichefactory-mcp\n   ```\n\n4. **Configure** — either paste the key into your MCP client (see below) **or** run once in a terminal:\n\n   ```bash\n   pip install clichefactory   # if you don't have the CLI yet\n   clichefactory configure\n   ```\n\n   The interactive wizard saves credentials to `~/.clichefactory/config.toml`, which the MCP server reads automatically.\n\nThat's it — one env var (`CLICHEFACTORY_API_KEY`) or a config file, and you're on hosted extraction.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `extract` | Extract structured JSON from a document using a schema |\n| `to_markdown` | Convert a document to markdown text |\n| `doctor` | Check configuration, dependencies, and system binaries |\n\n### `extract`\n\nThe main tool. Pass a document file and a JSON schema — get structured data back.\n\nSupports all extraction modes:\n\n| Mode | Description | Requires |\n|------|-------------|----------|\n| *(default)* | OCR + LLM extraction | Service API key (recommended) |\n| `fast` | Fastest pipeline | Service API key |\n| `trained` | Trained pipeline artifact | Service + `artifact_id` |\n| `robust` | Two-stage extract + verify | Service only |\n| `robust-trained` | Trained extract + verification | Service + `artifact_id` |\n\nThe schema can be provided as:\n- **File path**: absolute path to a `.json` schema file\n- **Inline dict**: the LLM constructs a JSON schema from the conversation (e.g., the user says *\"extract the invoice number and total\"* and the LLM builds `{\"type\": \"object\", \"properties\": {\"invoice_number\": {\"type\": \"string\"}, \"total\": {\"type\": \"number\"}}}`)\n\n### `to_markdown`\n\nConverts any supported document to markdown. Useful for inspecting document contents or feeding them to the LLM for analysis before deciding on an extraction schema.\n\n### `doctor`\n\nRuns diagnostics on the ClicheFactory setup — config file, API keys, Python dependencies, system binaries. Call this when things aren't working.\n\n## Execution Modes\n\nThe server defaults to **service mode** (ClicheFactory cloud). Local mode is available for BYOK / air-gapped use.\n\n- **`service`** *(recommended)* — Uses the ClicheFactory cloud service. Requires a ClicheFactory API key. Supports all extraction modes including trained pipelines and robust verification. Best extraction quality out of the box.\n\n- **`local`** *(advanced)* — Runs extraction on your machine. You bring your own LLM key (BYOK). Requires `pip install \"clichefactory-mcp[local]\"` (~2 GB of parsing/OCR dependencies) plus system binaries (tesseract, LibreOffice). Quality depends on your local setup.\n\n## Installation\n\n### Prerequisites\n\n- Python ≥ 3.12\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n\n### From PyPI\n\n```bash\npip install clichefactory-mcp\n```\n\nFor local-mode extraction (BYOK, runs on your machine), install with the local extras:\n\n```bash\npip install \"clichefactory-mcp[local]\"\n```\n\n## Configuration\n\n### Environment Variables\n\nSet these in your MCP client configuration (see below) or in `~/.clichefactory/config.toml` via `clichefactory configure`.\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `CLICHEFACTORY_API_KEY` | **Yes** (service mode) | ClicheFactory API key from Settings → API Keys (`cliche-...`) |\n| `CLICHEFACTORY_API_URL` | No | Override the default service URL (`https://api.clichefactory.com`); useful for local development against a self-hosted ClicheFactory backend |\n| `LLM_MODEL_NAME` | Local mode only | Model name, e.g. `gemini/gemini-3-flash-preview` |\n| `LLM_API_KEY` | Local mode only | API key for the LLM provider |\n| `OCR_MODEL_NAME` | No | Separate OCR/VLM model (defaults to main model) |\n| `OCR_API_KEY` | No | API key for OCR model (defaults to main key) |\n\nEnvironment variables take precedence over the config file at `~/.clichefactory/config.toml`.\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project (or global Cursor settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"clichefactory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"clichefactory-mcp\"],\n      \"env\": {\n        \"CLICHEFACTORY_API_KEY\": \"cliche-your-key-here\"\n      }\n    }\n  }\n}\n```\n\nFor local development from a git checkout, replace `uvx` with:\n\n```json\n\"command\": \"uv\",\n\"args\": [\"--directory\", \"/absolute/path/to/cliche-mcp\", \"run\", \"clichefactory-mcp\"]\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"clichefactory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"clichefactory-mcp\"],\n      \"env\": {\n        \"CLICHEFACTORY_API_KEY\": \"cliche-your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### OpenClaw\n\nRegister the MCP server with your [OpenClaw](https://github.com/openclaw/openclaw) agent:\n\n```bash\nopenclaw mcp set clichefactory '{\"command\":\"uvx\",\"args\":[\"clichefactory-mcp\"],\"env\":{\"CLICHEFACTORY_API_KEY\":\"cliche-your-key-here\"}}'\n```\n\nVerify with `openclaw mcp list`. The agent can now use `extract`, `to_markdown`, and `doctor` tools in any conversation.\n\nAn OpenClaw skill with agent instructions is also available in [`integrations/openclaw/`](integrations/openclaw/SKILL.md). To install it into your workspace:\n\n```bash\ncp -r /path/to/cliche-mcp/integrations/openclaw ~/.openclaw/skills/clichefactory\n```\n\nOr, once published to ClawHub:\n\n```bash\nopenclaw skills install clichefactory\n```\n\n### Local mode (advanced)\n\nIf you prefer BYOK extraction on your machine, install the local extras and set LLM credentials:\n\n```json\n{\n  \"mcpServers\": {\n    \"clichefactory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"clichefactory-mcp\"],\n      \"env\": {\n        \"LLM_MODEL_NAME\": \"gemini/gemini-3-flash-preview\",\n        \"LLM_API_KEY\": \"your-gemini-api-key\"\n      }\n    }\n  }\n}\n```\n\nPass `mode=\"local\"` explicitly in tool calls, or run `clichefactory configure --local` to set local as the default in `~/.clichefactory/config.toml`.\n\n## Supported File Types\n\nPDF, PNG, JPG, JPEG, WebP, GIF, BMP, DOCX, DOC, ODT, XLSX, CSV, EML, TXT, MD.\n\n## Differences from the CLI\n\nThis MCP server covers the core extraction and conversion workflows. The following CLI features are **not included** in v1:\n\n| Feature | Reason |\n|---------|--------|\n| Batch operations (`extract-batch`, `to-markdown-batch`) | MCP tools are typically called one-at-a-time by the LLM. For multiple documents, the LLM calls `extract` in sequence. Batch support may be added in a future version. |\n| `configure` | Interactive prompts don't work in MCP. Use env vars or run `clichefactory configure` in a terminal. |\n| `--output` / `-o` flag | MCP tools return results directly to the LLM rather than writing to files. |\n| `allow_partial` | Not exposed as a tool parameter in v1. |\n| OCR engine selection | Uses the SDK defaults (RapidOCR). Configure via `~/.clichefactory/config.toml` or pass parsing options through the SDK if needed. |\n\n## Development\n\n```bash\n# Install in development mode\nuv sync\n\n# Run the server directly (stdio transport, for testing with MCP clients)\nuv run clichefactory-mcp\n\n# Inspect available tools (requires mcp CLI)\nuv run mcp dev cliche_mcp/server.py\n```\n\n## License\n\n[MIT](LICENSE) — Copyright (c) 2026 Urban Susnik s.p.\n",
  "bytes": 8081,
  "sha": "788e3ac28c7127a7c479d318ba509519ac6e28a850a273b7f5df17fee3dc63e4",
  "repo_slug": "clichefactory/clichefactory-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_clichefactory_clichefactory_mc_4014dbb0/readme"
}