kuzhang/picture2excel-mcp

Picture2Excel (MCP server)

Extract text and tables from images using an MCP stdio server powered by OpenAI Vision. Output is Markdown for tables and nicely formatted Excel when saving.

1) Prerequisites

• UV
• claude desktop
• Python 3.10+
• An OpenAI API key

2) Setup

Create a .env file next to this README:

OPENAI_API_KEY=sk-...

Install dependencies (pip):

pip install -r requirements.txt

Or with uv (recommended):

uv installation instruction: https://docs.astral.sh/uv/getting-started/installation/

Windows (PowerShell):

uv venv .venv
uv pip install -r requirements.txt

macOS/Linux (bash/zsh):

uv venv .venv
uv pip install -r requirements.txt

Test Run the server using the venv Python （optional）:

Windows cmd terminal:

uv run mcp_server.py

macOS/Linux:

uv run mcp_server.py

3) Run the MCP server (stdio)

Register it in your MCP-compatible client (e.g., Cursor, Claude Desktop) by pointing to uv and argument mcp_server.py. Ensure the environment provides OPENAI_API_KEY.

Claude Desktop quick setup

• Install the app from the official site.
• Create (or edit) the MCP config file:
  • Windows: C:\Users\<YOU>\AppData\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Example config using the uv venv Python:

{
  "servers": {
    "picture2excel": {
      "command": "C:\\Users\\<YOU>\\Desktop\\AgenticAI\\code\\picture2excel\\.venv\\Scripts\\python.exe",
      "args": ["mcp_server.py"],
      "cwd": "C:\\Users\\<YOU>\\Desktop\\AgenticAI\\code\\picture2excel",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

On macOS, set command to /<project-path>/.venv/bin/python and adjust paths accordingly.

4) Available tools

• extract_tables(image_path: str, model: str = "gpt-4o-mini", save_to_excel: bool = False, dest_path: str = "output.xlsx")

  • Returns Markdown tables (or NONE). If save_to_excel=True, writes parsed tables into the Output sheet.

• extract_content(image_path: str, model: str = "gpt-4o-mini", save_to_excel: bool = False, dest_path: str = "output.xlsx")

  • Returns a Markdown document with a “Text” code block and a “Tables” section. If save_to_excel=True, writes the text and tables into a single Output sheet.

5) Tips

• For saving, the Excel layout preserves line breaks in text and formats tables with bold headers, borders, and auto column widths.
• If your client supports tool selection, you can ask: “Extract the content from picture.jpg and save it.”

6) Example prompts

• Extract tables (Markdown) from an image:

  • "Extract tables from C:\Users\\Desktop\AgenticAI\code\picture2excel\picture.jpg."
  • "Extract tables from /Users//Desktop/AgenticAI/code/picture2excel/picture.jpg."

• Extract text + tables and save to Excel:

  • "Extract the content from C:\Users\\Desktop\AgenticAI\code\picture2excel\picture.jpg and save it to C:\Users\\Desktop\AgenticAI\code\picture2excel\output.xlsx."
  • "Extract the content from /Users//Desktop/AgenticAI/code/picture2excel/picture.jpg and save it to /Users//Desktop/AgenticAI/code/picture2excel/output.xlsx."

• Save tables only to Excel:

  • "Extract tables from C:\path\to\image.jpg and save to excel as C:\path\to\tables.xlsx."

• Extract only text (no save):

  • "Extract only the text from C:\path\to\image.jpg."