ClicheFactory Document Intelligence

clichefactory-mcp

适用于 ClicheFactory 的 MCP（模型上下文协议）服务——从文档中提取结构化数据。

此服务将 ClicheFactory 的提取和文档转换功能作为 MCP 工具提供，使 Cursor、Claude Desktop、OpenClaw 及其他兼容 MCP 的客户端中的 AI 助手能够从 PDF、图片、DOCX、XLSX、CSV、EML 等文件中提取结构化数据。

快速开始（推荐 — 服务模式）

服务模式使用 ClicheFactory 云服务，以获得最佳提取质量。您只需要一个 API 密钥。

1. 注册：clichefactory.com——包含免费页面，无需信用卡。

2. 创建 API 密钥：前往 Settings → API Keys（格式：cliche-...）。

3. 安装 MCP 服务：

   pip install clichefactory-mcp
   

4. 配置——将密钥粘贴到 MCP 客户端中（见下文），或在终端中运行一次：

   pip install clichefactory   # if you don't have the CLI yet
   clichefactory configure
   

   交互式向导会将凭据保存到 ~/.clichefactory/config.toml，MCP 服务会自动读取该文件。

完成——只需一个环境变量（CLICHEFACTORY_API_KEY）或一个配置文件，即可使用托管提取服务。

工具

工具	描述
extract	使用架构从文档中提取结构化 JSON
to_markdown	将文档转换为 Markdown 文本
doctor	检查配置、依赖项和系统二进制文件

extract

主要工具。传入文档文件和 JSON 架构，即可获取结构化数据。

支持所有提取模式：

模式	描述	需要
（默认）	OCR + 大模型提取	服务 API 密钥（推荐）
fast	最快的处理流程	服务 API 密钥
trained	经过训练的处理流程工件	服务 + artifact_id
robust	两阶段提取 + 验证	仅需服务
robust-trained	经过训练的提取 + 验证	服务 + artifact_id

架构可以通过以下方式提供：

• 文件路径：.json 架构文件的绝对路径
• 内联字典：大模型根据对话构建 JSON 架构（例如，用户说 “提取发票编号和总额”，大模型便会构建 {"type": "object", "properties": {"invoice_number": {"type": "string"}, "total": {"type": "number"}}}）

to_markdown

将任何受支持的文档转换为 Markdown。可用于检查文档内容，或在确定提取架构前将内容提供给大模型进行分析。

doctor

对 ClicheFactory 设置运行诊断——包括配置文件、API 密钥、Python 依赖项和系统二进制文件。遇到问题时调用此工具。

执行模式

服务默认使用服务模式（ClicheFactory 云服务）。也可使用本地模式，适用于 BYOK／隔离网络环境。

• service （推荐） — 使用 ClicheFactory 云服务。需要 ClicheFactory API 密钥。支持所有提取模式，包括经过训练的处理流程和稳健验证。开箱即用，提取质量最佳。

• local （高级） — 在您的机器上运行提取。您需要自备大模型密钥（BYOK）。需要执行 pip install "clichefactory-mcp[local]"（约 2 GB 的解析／OCR 依赖项），以及系统二进制文件（tesseract、LibreOffice）。质量取决于您的本地设置。

安装

前提条件

• Python ≥ 3.12
• uv（推荐）或 pip

从 PyPI 安装

pip install clichefactory-mcp

如需在本地模式下提取（BYOK，在您的机器上运行），请安装本地扩展：

pip install "clichefactory-mcp[local]"

配置

环境变量

在 MCP 客户端配置中（见下文）或通过 clichefactory configure 在 ~/.clichefactory/config.toml 中设置这些变量。

变量	必填	说明
CLICHEFACTORY_API_KEY	是（服务模式）	ClicheFactory API 密钥，可在 Settings → API Keys 中获取（cliche-...）
CLICHEFACTORY_API_URL	否	覆盖默认服务 URL（https://api.clichefactory.com）；适用于在可自托管的 ClicheFactory 后端上进行本地开发
LLM_MODEL_NAME	仅本地模式	模型名称，例如 gemini/gemini-3-flash-preview
LLM_API_KEY	仅本地模式	大模型提供商的 API 密钥
OCR_MODEL_NAME	否	单独的 OCR/VLM 模型（默认为主模型）
OCR_API_KEY	否	OCR 模型的 API 密钥（默认为主密钥）

环境变量的优先级高于 ~/.clichefactory/config.toml 中的配置。

Cursor

将以下内容添加到项目中的 .cursor/mcp.json（或 Cursor 全局设置）：

{
  "mcpServers": {
    "clichefactory": {
      "command": "uvx",
      "args": ["clichefactory-mcp"],
      "env": {
        "CLICHEFACTORY_API_KEY": "cliche-your-key-here"
      }
    }
  }
}

若要从 git 检出目录进行本地开发，请将 uvx 替换为：

"command": "uv",
"args": ["--directory", "/absolute/path/to/cliche-mcp", "run", "clichefactory-mcp"]

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "clichefactory": {
      "command": "uvx",
      "args": ["clichefactory-mcp"],
      "env": {
        "CLICHEFACTORY_API_KEY": "cliche-your-key-here"
      }
    }
  }
}

OpenClaw

向你的 OpenClaw Agent 注册 MCP 服务：

openclaw mcp set clichefactory '{"command":"uvx","args":["clichefactory-mcp"],"env":{"CLICHEFACTORY_API_KEY":"cliche-your-key-here"}}'

使用 openclaw mcp list 验证。现在，Agent 可以在任何对话中使用 extract、to_markdown 和 doctor 工具。

integrations/openclaw/ 中还提供了包含 Agent 指令的 OpenClaw 技能。要将其安装到工作区：

cp -r /path/to/cliche-mcp/integrations/openclaw ~/.openclaw/skills/clichefactory

或者，在 ClawHub 上发布后：

openclaw skills install clichefactory

本地模式（高级）

如果你希望在自己的机器上使用 BYOK 提取，请安装本地扩展并设置大模型凭据：

{
  "mcpServers": {
    "clichefactory": {
      "command": "uvx",
      "args": ["clichefactory-mcp"],
      "env": {
        "LLM_MODEL_NAME": "gemini/gemini-3-flash-preview",
        "LLM_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

在工具调用中明确传入 mode="local"，或运行 clichefactory configure --local，将本地模式设为 ~/.clichefactory/config.toml 中的默认模式。

支持的文件类型

PDF、PNG、JPG、JPEG、WebP、GIF、BMP、DOCX、DOC、ODT、XLSX、CSV、EML、TXT、MD。

与 CLI 的差异

此 MCP 服务涵盖核心提取和转换工作流。以下 CLI 功能未包含在 v1 中：

功能	原因
批量操作（extract-batch、to-markdown-batch）	大模型通常一次调用一个 MCP 工具。处理多个文档时，大模型会依次调用 extract。未来版本可能会增加批量支持。
configure	交互式提示在 MCP 中无法使用。请使用环境变量，或在终端中运行 clichefactory configure。
--output / -o 标志	MCP 工具会直接向大模型返回结果，而不是将结果写入文件。
allow_partial	v1 中未将其作为工具参数提供。
OCR 引擎选择	使用 SDK 默认设置（RapidOCR）。如有需要，可通过 ~/.clichefactory/config.toml 配置，或通过 SDK 传入解析选项。

开发

# Install in development mode
uv sync

# Run the server directly (stdio transport, for testing with MCP clients)
uv run clichefactory-mcp

# Inspect available tools (requires mcp CLI)
uv run mcp dev cliche_mcp/server.py

许可证

MIT — 版权所有 (c) 2026 Urban Susnik s.p.