文档解析服务

SoMark MCP Server

English | 中文

A Model Context Protocol (MCP) server for SoMark's document parsing API. It parses PDF and image files into Markdown, JSON format with high accuracy.

Quick Start

1. Get your API Key

• Mainland China (中国大陆): somark.cn/workbench/apikey
• Outside mainland China (including Taiwan, China; Hong Kong, China; Macau, China): somark.ai/workbench/apikey
• Purchase an API plan:
  • Mainland China: somark.cn/workbench/purchase
  • Global: somark.ai/studio/purchase

2. Add the following to your MCP client configuration (Claude Desktop, VS Code, Cursor, etc.):

{
    "mcpServers": {
        "somark": {
            "command": "npx",
            "args": ["-y", "somark-mcp"],
            "env": {
                "SOMARK_API_KEY": "your-api-key-here",
                "SOMARK_API_BASE_URL": "https://somark.cn/api/v1"
            }
        }
    }
}

3. Done! Ask your AI assistant to parse any PDF or image file.

API Base URL Configuration

Set the SOMARK_API_BASE_URL environment variable to choose the server region:

The server automatically derives the web, docs, and purchase URLs from SOMARK_API_BASE_URL:

Available Tools

check_api_key

Check whether the SoMark API key is configured and ready to use.

set_api_key

Set or update the SoMark API key at runtime (useful when the environment variable is not set).

extract_document

Parse PDF or image files (PNG, JPG, JPEG, BMP, TIFF, JP2, DIB, PPM, PGM, PBM, GIF, HEIC, HEIF, WebP, XPM, TGA, DDS, XBM) into markdown, json format.

element_formats fields:

• image: "url" | "base64" | "none", default url
• formula: "latex" | "mathml" | "ascii", default latex
• table: "html" | "markdown" | "image", default html
• cs: "image", default image

feature_config fields:

• enable_text_cross_page: boolean, default false
• enable_table_cross_page: boolean, default false
• enable_title_level_recognition: boolean, default false
• enable_inline_image: boolean, default true
• enable_table_image: boolean, default true
• enable_image_understanding: boolean, default true
• keep_header_footer: boolean, default false

Supported file formats:

• PDF (.pdf)
• PNG (.png)
• JPEG (.jpg, .jpeg)
• BMP (.bmp, .dib)
• TIFF (.tiff, .tif)
• JPEG 2000 (.jp2)
• Portable Pixmap (.ppm)
• Portable Graymap (.pgm)
• Portable Bitmap (.pbm)
• GIF (.gif)
• HEIC (.heic)
• HEIF (.heif)
• WebP (.webp)
• X PixMap (.xpm)
• Targa (.tga)
• DirectDraw Surface (.dds)
• X BitMap (.xbm)

Example usage:

// Parse a PDF to Markdown
{
  "file_path": "/path/to/document.pdf",
  "output_formats": ["markdown"]
}

// Parse an image to JSON
{
  "file_path": "/path/to/image.png",
  "output_formats": ["json"]
}

Development

pnpm install          # Install dependencies
pnpm build            # Build the project
pnpm exec tsc --noEmit  # Type check

Testing

pnpm test             # Full MCP server test
pnpm test:api         # API connection test

Troubleshooting

License

ISC