Somark MCP Server

English | 中文

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

Quick Start

1. Get your API Key → somark.tech/workbench/apikey

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

{
  "mcpServers": {
    "somark": {
      "command": "npx",
      "args": ["-y", "github:SoMarkAI/somark_mcp"],
      "env": {
        "SOMARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

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

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).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | api_key | string | Yes | Your Somark API key from somark.tech |

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) to Markdown or JSON format.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | file_path | string | Yes | — | Absolute path to the PDF or image file | | output_format | "markdown" | "json" | No | "markdown" | Output format | | extract_images | boolean | No | false | Whether to extract images from the document | | language | string | No | auto-detect | Language code (e.g., en, zh, ja) |

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_format": "markdown"
}

// Parse an image to JSON with image extraction
{
  "file_path": "/path/to/image.png",
  "output_format": "json",
  "extract_images": true,
  "language": "en"
}

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

See test/README.md for details.

Troubleshooting

| Problem | Solution | |---------|----------| | "API key not configured" | Add SOMARK_API_KEY to your MCP client config, or use the set_api_key tool | | Connection issues | Check that your API key is valid and somark.tech is accessible | | Unsupported file format | Supports PDF, PNG, JPG, JPEG, BMP, TIFF, JP2, DIB, PPM, PGM, PBM, GIF, HEIC, HEIF, WebP, XPM, TGA, DDS, XBM formats |

License

ISC