MCP Server

Expose ClicheFactory extraction and conversion tools to AI coding assistants via the Model Context Protocol.

What is MCP

The Model Context Protocol (MCP) lets AI assistants call external tools. The ClicheFactory MCP server exposes extract, to_markdown, and doctor tools — your assistant can extract data from documents and convert them to markdown as part of your conversation.

Quick Start (recommended — service mode)

Service mode uses the ClicheFactory cloud for the best extraction quality. You only need one API key.

Sign up — free pages included, no credit card — then create an API key in Settings → API Keys (cliche-...).
Add the MCP server to Cursor, Claude Desktop, or OpenClaw (examples below). No separate install step — uvx fetches clichefactory-mcp automatically.
Paste your key as CLICHEFACTORY_API_KEY in the MCP client config, or run clichefactory configure once in a terminal (saves to ~/.clichefactory/config.toml, which the MCP server reads automatically).
Restart your IDE and ask your assistant to extract from a document.

In chat, the assistant builds JSON schemas inline from your request — that's the natural MCP workflow. Saved config_id references are for the SDK and REST API, not MCP.

Setup — Cursor

Add to your .cursor/mcp.json (project-level) or Cursor settings (global):

Service Mode (recommended)

        {

          "mcpServers": {

            "clichefactory": {

              "command": "uvx",

              "args": ["clichefactory-mcp"],

              "env": {

                "CLICHEFACTORY_API_KEY": "cliche-your-key"

              }

            }

          }

        }

Local Mode (advanced — BYOK)

For on-machine extraction with your own LLM key. Requires pip install "clichefactory-mcp[local]" (~2 GB of parsing/OCR dependencies) and system binaries (Tesseract, LibreOffice).

        {

          "mcpServers": {

            "clichefactory": {

              "command": "uvx",

              "args": ["clichefactory-mcp"],

              "env": {

                "LLM_MODEL_NAME": "gemini/gemini-3-flash-preview",

                "LLM_API_KEY": "your-gemini-key"

              }

            }

          }

        }

After saving, restart Cursor. The tools should appear in your MCP tools list.

Setup — Claude Desktop

Edit your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Service Mode (recommended)

        {

          "mcpServers": {

            "clichefactory": {

              "command": "uvx",

              "args": ["clichefactory-mcp"],

              "env": {

                "CLICHEFACTORY_API_KEY": "cliche-your-key"

              }

            }

          }

        }

Local Mode (advanced — BYOK)

        {

          "mcpServers": {

            "clichefactory": {

              "command": "uvx",

              "args": ["clichefactory-mcp"],

              "env": {

                "LLM_MODEL_NAME": "gemini/gemini-3-flash-preview",

                "LLM_API_KEY": "your-gemini-key"

              }

            }

          }

        }

Restart Claude Desktop after saving. The ClicheFactory tools will be available in your conversations.

Setup — OpenClaw

For OpenClaw, install the ClicheFactory skill — see the OpenClaw page for full setup. Register the MCP server with your service API key:

        openclaw mcp set clichefactory '{

          "command": "uvx",

          "args": ["clichefactory-mcp"],

          "env": {"CLICHEFACTORY_API_KEY": "cliche-your-key"}

        }'

Tools Reference

The MCP server exposes three tools:

`extract`

Extract structured data from a document using a JSON schema.

Parameter	Type	Required	Description
`file`	string	Yes	Absolute path to the document file.
`schema`	string or object	Yes	JSON Schema (file path or inline object).
`mode`	string	No	`service` (default) or `local`. Auto-detected from credentials when omitted.
`extraction_mode`	string	No	`fast`, `robust`, `trained`. Trained mode auto-resolves when `artifact_id` is provided.
`artifact_id`	string	No	Trained pipeline artifact ID (service only).
`model`	string	No	LLM model override (BYOK).
`model_api_key`	string	No	API key for the model override.
`ocr_model`	string	No	Separate model for OCR/VLM tasks.
`ocr_api_key`	string	No	API key for the OCR model.

`to_markdown`

Convert a document to markdown text.

Parameter	Type	Required	Description
`file`	string	Yes	Absolute path to the document file.
`mode`	string	No	`service` (default) or `local`. Auto-detected from credentials when omitted.
`conversion_mode`	string	No	`default` (full OCR pipeline) or `fast` (VLM-only, no OCR). Service mode only.
`model`	string	No	LLM model override.
`model_api_key`	string	No	API key for the model override.
`ocr_model`	string	No	Separate model for OCR/VLM tasks.
`ocr_api_key`	string	No	API key for the OCR model.

`doctor`

Check ClicheFactory configuration, dependencies, and system binaries. No parameters. Call this when extraction fails or to verify setup. In service mode, local parsing dependencies are reported as informational — not required.

Execution Modes

Service mode is the default and recommended setup. Set CLICHEFACTORY_API_KEY in your MCP client config (or run clichefactory configure) and ClicheFactory handles parsing, OCR, and extraction in the cloud — best quality out of the box, including robust and trained pipelines.

Local mode (advanced) runs extraction on your machine with your own LLM key. Install clichefactory-mcp[local] and set LLM_MODEL_NAME / LLM_API_KEY. Quality depends on your local setup. See Core Concepts → Execution Modes for details.