MCP-VizAPI: Visual Data Extraction with VizAPI.ai

VizAPI and MCP Integration

An MCP server integrated with [VizAPI.ai](https://vizapi.ai) for extracting structured data from images and documents. This server allows AI agents compatible with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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: ```bash pip install uv ``` 2. Clone this repository: ```bash git clone # Replace with actual repo URL cd vizapi-mcp-server ``` 3. Install dependencies: ```bash 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): ```bash cp .env.example .env ``` If `.env.example` doesn't exist, create `.env` with the following content: ```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: ```bash docker build -t mcp/vizapi --build-arg PORT=8060 . ``` *(Ensure your Dockerfile EXPOSE directive matches this port if changed)* 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 ```bash # Set TRANSPORT=sse in .env (or ensure it's the default) # Ensure VIZAPI_API_KEY is set in .env uv run src/main.py ``` The server will start, and you should see output indicating it's running, e.g.: `Starting VizAPI MCP server with SSE transport on http://0.0.0.0:8060/sse` #### 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 ```bash 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): ```json { "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`. > ```json > { > "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: ```json { "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 } } } } ``` *Ensure the `command` and `args` paths are correct for your system.* ### Docker with Stdio Configuration ```json { "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](https://github.com/modelcontextprotocol/fastmcp) for more details on creating MCP servers.

VizAPI

MCP-VizAPI Server