<h1 align="center">MCP-VizAPI: Visual Data Extraction with VizAPI.ai</h1>

<p align="center">

<!-- Consider creating a new banner image, placeholder text for now -->
</p>

An MCP server integrated with VizAPI.ai for extracting structured data from images and documents.

This server allows AI agents compatible with the Model Context Protocol (MCP) to leverage VizAPI's powerful visual data extraction capabilities.

Overview

This project provides an MCP server that enables AI agents to:
- List available extraction templates.
- Retrieve specific extraction templates.
- Suggest fields for extraction from a new document/image.
- Extract data from documents/images using predefined templates.
- Check the health of the VizAPI service.

The implementation follows best practices for MCP servers, allowing seamless integration with any MCP-compatible client.

Features

The server provides the following tools for interacting with VizAPI.ai:

1. get_template_by_id: Retrieve a specific extraction template by its ID.
2. list_templates: Get all private templates for the authenticated user.
3. suggest_fields: Analyze a document/image and suggest fields for extraction.
4. extract_values: Extract structured data from a document/image using a template.
5. health_check: Check the operational status of the VizAPI.ai service.

Prerequisites

- Python 3.12+
- A VizAPI.ai account and API key.
- Docker if running the MCP server as a container (recommended).

Installation

Using uv

1. Install uv if you don't have it:

    pip install uv

    

2. Clone this repository:

    git clone <your_repository_url_here> # Replace with actual repo URL

    cd vizapi-mcp-server 

    

3. Install dependencies:

    uv pip install -e .

    

4. Create a .env file based on .env.example (you might need to create this file if it doesn't exist):

    cp .env.example .env 

    

    # Transport protocol: 'sse' (Server-Sent Events) or 'stdio' (Standard I/O)

    TRANSPORT="sse"

# Host and Port for SSE transport

    HOST="0.0.0.0"

    PORT="8060" # Default port for VizAPI MCP server
# VizAPI Configuration

    VIZAPI_API_KEY="YOUR_VIZAPI_API_KEY" 

    # Get your API key from https://app.vizapi.ai/dashboard

    

5. Configure your environment variables in the .env file, especially VIZAPI_API_KEY.

Using Docker (Recommended)

1. Build the Docker image:

    docker build -t mcp/vizapi --build-arg PORT=8060 .

    

2. Create a .env file as described above and configure your VIZAPI_API_KEY.

Configuration

The following environment variables can be configured in your .env file:

| Variable | Description | Example |
| ---------------- | --------------------------------------------------- | --------------------------------- |
| TRANSPORT | Transport protocol (sse or stdio) | sse |
| HOST | Host to bind to when using SSE transport | 0.0.0.0 |
| PORT | Port to listen on when using SSE transport (default: 8060) | 8060 |
| VIZAPI_API_KEY | Your API key for VizAPI.ai | viz_sk_xxxxxxxxxxxxxxxxxxxxxxxx |

Important: You MUST set the VIZAPI_API_KEY for the server to function.

Running the Server

Using uv

SSE Transport

# Set TRANSPORT=sse in .env (or ensure it's the default)
Ensure VIZAPI_API_KEY is set in .env
uv run src/main.py

Stdio Transport

Ensure TRANSPORT=stdio and VIZAPI_API_KEY are set in your .env file if you plan to use this method with an MCP client that launches the server directly. The client configuration will need to pass these environment variables.

Using Docker

SSE Transport

docker run --env-file .env -p 8060:8060 mcp/vizapi 
Ensure the host port (first 8060) matches your .env PORT if different
Ensure the container port (second 8060) matches the EXPOSE directive in Dockerfile and .env PORT

The MCP server will run inside the container, accessible on the host at the specified port.

Stdio Transport

For stdio transport with Docker, the MCP client will manage the docker run command. The client's configuration will need to correctly pass the VIZAPI_API_KEY and other necessary environment variables to the container.

Integration with MCP Clients

SSE Configuration

Once the server is running with SSE transport, connect to it using this configuration in your MCP client (e.g., Claude Desktop, Windsurf):

{
  "mcpServers": {
    "vizapi": {
      "transport": "sse",
      "url": "http://localhost:8060/sse" 
      // Adjust host and port if your server is running elsewhere or on a different port
    }
  }
}

> Note for Windsurf users: Use serverUrl instead of url.
>

> {

>   "mcpServers": {

>     "vizapi": {

>       "transport": "sse",

>       "serverUrl": "http://localhost:8060/sse"

>     }

>   }

> }

> 

> Note for n8n users: If n8n is running in Docker and the VizAPI MCP server is on the host machine, use http://host.docker.internal:8060/sse.

Python with Stdio Configuration (Example for clients like Claude Desktop)

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "vizapi": {
      "command": "your/path/to/vizapi-mcp-server/.venv/bin/python", // Adjust path to python in your venv
      "args": ["your/path/to/vizapi-mcp-server/src/main.py"],
      "env": {
        "TRANSPORT": "stdio",
        "VIZAPI_API_KEY": "YOUR_VIZAPI_API_KEY"
        // Add HOST and PORT if needed by your specific stdio setup, though usually not for stdio
      }
    }
  }
}

Docker with Stdio Configuration

{
  "mcpServers": {
    "vizapi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "TRANSPORT=stdio", 
               "-e", "VIZAPI_API_KEY=YOUR_VIZAPI_API_KEY",
               // Add other env vars like HOST, PORT if necessary for your setup
               "mcp/vizapi"], // Your built Docker image name
      "env": { 
        // This outer env is for the client environment, ensure it doesn't conflict
        // The critical VIZAPI_API_KEY is passed via -e to the container
      }
    }
  }
}

Building Your Own Server (Extending this Template)

This template serves as a starting point. You can extend it by:

1. Adding new tools for other VizAPI endpoints or custom logic using @mcp.tool().
2. Modifying the VizAPIContext or vizapi_lifespan if you need to manage more complex state or resources.
3. Adding prompts (@mcp.prompt()) or resources (@mcp.resource()) if your use case requires them.

Refer to the FastMCP documentation for more details on creating MCP servers.