TextIn xParse MCP Server

SSE MCP server for TextIn xParse document parsing.

The server exposes these MCP tools:

• parse_run: maps to client.parse.run()
• parse_run_url: downloads a file URL, then maps to client.parse.run()
• parse_create_job: maps to client.parse.create_job()
• parse_get_job: maps to client.parse.get_job()
• parse_wait_job: maps to client.parse.wait_job()

Setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .

Configure authentication with environment variables only:

$env:TEXTIN_APP_ID="your-app-id"
$env:TEXTIN_SECRET_CODE="your-secret-code"

Do not pass credentials as MCP tool arguments. The server constructs XParseClient() without explicit credentials so the official SDK reads its environment variables.

To use a custom TextIn-compatible server address, set TEXTIN_SERVER_URL:

$env:TEXTIN_SERVER_URL="https://your-server.example.com"

When TEXTIN_SERVER_URL is unset, the official SDK default server is used.

The MCP tools accept file content as base64 or as a downloadable file URL. Decoded or downloaded file size is limited by MAX_FILE_BYTES, which defaults to 52428800 bytes.

Run

textin-mcp

The default transport is SSE. You can also pass an explicit transport:

textin-mcp --transport sse

The server listens on 127.0.0.1:8000 by default. Override this for container or remote access:

$env:MCP_HOST="0.0.0.0"
$env:MCP_PORT="8000"
textin-mcp --transport sse

Docker

Build the image:

docker build -t textin-mcp .

Run the SSE MCP server:

docker run --rm -p 8000:8000 `
  -e TEXTIN_APP_ID="your-app-id" `
  -e TEXTIN_SECRET_CODE="your-secret-code" `
  -e TEXTIN_SERVER_URL="https://your-server.example.com" `
  -e MAX_FILE_BYTES="52428800" `
  textin-mcp

Or run with Docker Compose:

docker compose up --build

Compose reads TEXTIN_APP_ID, TEXTIN_SECRET_CODE, optional TEXTIN_SERVER_URL, and optional MAX_FILE_BYTES from your environment or .env file. It starts the MCP SSE service on host port 8004 and the file-to-base64 helper on host port 8005.

File to Base64 Helper

The helper is a regular HTTP service, not an MCP SSE endpoint. It accepts a multipart file upload and returns the payload needed by parse_run or parse_create_job.

Run locally:

textin-file-base64

By default it listens on 0.0.0.0:8001. Override with:

$env:FILE_BASE64_HOST="0.0.0.0"
$env:FILE_BASE64_PORT="8001"
textin-file-base64

Request:

curl.exe -X POST "http://127.0.0.1:8005/file-to-base64" `
  -F "file=@D:\docs\example.pdf"

Response:

{
  "filename": "example.pdf",
  "mime_type": "application/pdf",
  "size": 12345,
  "base64": "JVBERi0x..."
}

The same service also provides a simple browser upload and download UI:

• GET /: upload page
• POST /upload: upload and store a file
• GET /files/{file_id}: download a stored file
• GET /files/{file_id}/base64: get stored file content as base64

POST /upload returns:

{
  "file_id": "abc123",
  "filename": "example.pdf",
  "mime_type": "application/pdf",
  "size": 12345,
  "download_url": "http://168.8.6.168:8005/files/abc123",
  "base64_url": "http://168.8.6.168:8005/files/abc123/base64"
}

Stored files are written under FILE_STORAGE_DIR, which defaults to /data/files in the container. Docker Compose mounts this path to the file_storage volume.

Uploaded files are cleaned up automatically. By default, files older than 7 days are removed every hour:

$env:FILE_RETENTION_SECONDS="604800"
$env:FILE_CLEANUP_INTERVAL_SECONDS="3600"

Set FILE_RETENTION_SECONDS=0 to disable automatic cleanup.

Set FILE_PUBLIC_BASE_URL when users access the helper from another machine so upload results contain complete URLs with the reachable host:

$env:FILE_PUBLIC_BASE_URL="http://168.8.6.168:8005"
docker compose up --build

Tools

parse_run

Synchronously parse a base64-encoded document.

Parameters:

• filename: document filename, for example example.pdf
• file_base64: base64-encoded document content
• page_range: optional page range, for example 1-10
• password: optional encrypted PDF password
• include_hierarchy
• include_inline_objects
• include_char_details
• include_image_data
• include_table_structure
• pages
• title_tree
• table_view: markdown or html

parse_run_url

Synchronously parse a document from a downloadable file URL.

Parameters:

• file_url: downloadable file URL, for example http://168.8.6.168:8005/files/abc123
• filename: optional document filename override; when omitted, the filename is inferred from file_url
• all parse configuration parameters supported by parse_run

parse_create_job

Create an asynchronous parsing job.

Parameters:

• filename: document filename, for example example.pdf
• file_base64: base64-encoded document content
• webhook: optional completion callback URL
• all parse configuration parameters supported by parse_run

parse_get_job

Query an asynchronous parsing job.

Parameters:

• job_id

parse_wait_job

Poll until an asynchronous parsing job finishes.

Parameters:

• job_id
• timeout: default 300.0
• poll_interval: default 5.0
• download_result: when true, downloads result_url after completion

MCP Client Example

{
  "mcpServers": {
    "textin-xparse": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Reference

• TextIn Python SDK documentation: https://docs.textin.com/xparse/v1/sdk-python