@kliper-ai/mcp

A Model Context Protocol server that lets MCP clients (Claude Desktop, Cursor, and others) call the Kliper document-extraction API.

It exposes tools to submit documents, check their status, and fetch the extracted structured data, plus a convenience tool that submits and waits for the result.

📖 Full API documentation: https://api.kliper.ai/docs

Requirements

• Node.js >= 20
• A Kliper API key (looks like kp_live_...)

Configuration

The server reads two environment variables:

| Variable | Required | Default | Description | | ----------------- | -------- | ------------------------------------------ | -------------------------------------------------- | | KLIPER_KEY | yes | — | Your Kliper API key (kp_live_... or kp_test_...). | | KLIPER_BASE_URL | no | picked from the key prefix (see below) | API base URL override. |

The server exits with a clear error if KLIPER_KEY is not set.

Sandbox vs live

The key prefix decides the environment automatically, so you don't set a URL:

• kp_live_... → https://api.kliper.ai/v1 (production, consumes credits)
• kp_test_... → https://api-sandbox.kliper.ai/v1 (free sandbox, capped at 25 docs/24h)

Set KLIPER_BASE_URL only to override this (e.g. self-hosted or a preview host).

MCP client config

Add this to your MCP client configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "kliper": {
      "command": "npx",
      "args": ["-y", "@kliper-ai/mcp"],
      "env": {
        "KLIPER_KEY": "kp_live_..."
      }
    }
  }
}

Tools

kliper_list_document_types

No inputs. Returns the document types this key can extract, each with a slug to pass as documentType. You can also pass "auto" to let Kliper detect the type.

kliper_extract_document

Submit a document for extraction. Provide exactly one source.

| Input | Type | Required | Notes | | -------------- | ------ | -------- | ------------------------------------------------------------ | | filePath | string | one-of | Path to a local PDF to upload. | | base64 | string | one-of | Base64-encoded file contents. | | url | string | one-of | Public https URL of a PDF; Kliper fetches it. | | fileName | string | no | Filename to attach for base64 uploads. | | documentType | string | yes | Type slug or name (see kliper_list_document_types), or "auto". | | callbackUrl | string | no | Webhook URL called on completion. | | metadata | object | no | Arbitrary metadata, echoed back on the result and webhook. |

Returns the submit response, including documentId and initial status.

kliper_get_status

| Input | Type | Required | Notes | | ------------ | ------ | -------- | ---------------------------------------------- | | documentId | string | yes | The id returned by kliper_extract_document. |

Returns the document status payload (queued, processing, success, requires_review, error, ...).

kliper_get_result

| Input | Type | Required | Notes | | ------------ | ------ | -------- | ---------------------------------------------- | | documentId | string | yes | The id returned by kliper_extract_document. |

Returns the extracted structured data. Available once status is success, requires_review, or partial_success.

kliper_extract_and_wait

Submit a document, poll status until terminal, then return the result.

| Input | Type | Required | Notes | | ---------------- | ------ | -------- | ------------------------------------------------------------ | | filePath | string | one-of | Path to a local PDF to upload. | | base64 | string | one-of | Base64-encoded file contents. | | url | string | one-of | Public https URL of a PDF; Kliper fetches it. | | fileName | string | no | Filename to attach for base64 uploads. | | documentType | string | yes | Type slug or name (see kliper_list_document_types), or "auto". | | metadata | object | no | Arbitrary metadata. | | timeoutMs | number | no | Max wait in ms (default 120000). | | pollIntervalMs | number | no | Poll interval in ms (default 3000). |

Returns { documentId, status, result } on success, or the terminal status payload on failure.

kliper_get_webhook_secret

No inputs. Returns { webhookSecret } — this organization's secret for verifying the X-Kliper-Signature header on webhook deliveries (see callbackUrl above). Generated on first call.

kliper_rotate_webhook_secret

No inputs. Generates a new webhook secret, invalidating the previous one immediately. Use if the secret may have leaked.

Development

npm install
npm run build      # compile TypeScript to dist/
npm run smoke      # node --check + construct the server without credentials
npm run dev        # tsc --watch

How it works

The server uses the stdio transport from the official @modelcontextprotocol/sdk. It wraps the Kliper REST API (GET /document-types, POST /documents, GET /documents/{id}, GET /documents/{id}/result) with Authorization: Bearer ${KLIPER_KEY}. API and network errors are returned to the client as tool errors rather than crashing the server.

License

MIT