Pixeltable

Pixeltable MCP Server lets you deploy a local MCP endpoint that coordinates Pixeltable’s data sources and analysis actions. It enables Claude or Cursor to interact with Pixeltable’s capabilities, run Python-based modules, and manage data workflows in a unified, extensible way.

How to use

You connect to Pixeltable through an MCP client by configuring a local MCP server entry. Once configured, you can issue commands to create and manage tables, run analyses, and orchestrate data workflows across images, audio, and documents.

Key usage patterns include: setting a datastore path, launching a persistent Python session with Pixeltable pre-loaded, and using built-in tools to log bugs or introspect available functions. Use natural language prompts to Claude or Cursor to trigger operations like creating a table, running object detection, or generating embeddings for search.

How to install

Prerequisites you must have installed before starting: the uv runtime. If you are unsure whether uv is installed, install it with the following command.

curl -LsSf https://astral.sh/uv/install.sh | sh

Choose one of the installation paths below based on your preference for either using a prebuilt tool or building from source.

Install as a global tool (simplest):

uv tool install --from git+https://github.com/pixeltable/mcp-server-pixeltable-developer.git mcp-server-pixeltable-developer

# Optional: add to Claude Code
claude mcp add pixeltable mcp-server-pixeltable-developer

# Update to latest version
uv tool install --force --from git+https://github.com/pixeltable/mcp-server-pixeltable-developer.git mcp-server-pixeltable-developer

Install from source (development):

git clone https://github.com/pixeltable/mcp-server-pixeltable-developer
cd mcp-server-pixeltable-developer
uv sync

Configuration for Claude Desktop

Add the Pixeltable MCP server to your Claude Desktop configuration. You can point Claude to a ready-made binary or to a source-based runner.

{
  "mcpServers": {
    "pixeltable": {
      "command": "mcp-server-pixeltable-developer",
      "env": {
        "PIXELTABLE_HOME": "/Users/{your-username}/.pixeltable",
        "PIXELTABLE_FILE_CACHE_SIZE_G": "10"
      }
    }
  }
}

If you are running from source instead of a prebuilt binary, configure Claude Desktop to start the server from the local repo path.

{
  "mcpServers": {
    "pixeltable": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "{path-to-your-repo}",
        "python",
        "-m",
        "mcp_server_pixeltable_stio"
      ],
      "env": {
        "PIXELTABLE_HOME": "/Users/{your-username}/.pixeltable",
        "PIXELTABLE_FILE_CACHE_SIZE_G": "10"
      }
    }
  }
}

Configuration for Cursor

Cursor users can add the Pixeltable MCP server to their MCP configuration either through Cursor Settings or by editing the JSON directly.

Via Cursor Settings:

# Cursor Settings UI: Features -> Model Context Protocol
# Add a new MCP server with command: mcp-server-pixeltable-developer

Via JSON Configuration (same as Claude Desktop example):

{
  "mcpServers": {
    "pixeltable": {
      "command": "mcp-server-pixeltable-developer",
      "env": {
        "PIXELTABLE_HOME": "/Users/{your-username}/.pixeltable",
        "PIXELTABLE_FILE_CACHE_SIZE_G": "10"
      }
    }
  }
}

For development or source installations, configure Cursor to start from uv and run the Python module from the repository.

{
  "mcpServers": {
    "pixeltable": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "{path-to-your-repo}",
        "python",
        "-m",
        "mcp_server_pixeltable_stio"
      ],
      "env": {
        "PIXELTABLE_HOME": "/Users/{your-username}/.pixeltable",
        "PIXELTABLE_FILE_CACHE_SIZE_G": "10"
      }
    }
  }
}

Examples

Create and populate a table by issuing natural language prompts to Claude. For example, you can say: Create a table for my screenshots, Add object detection to all images, Transcribe any audio files with Whisper.

Do local AI analysis and data workflows by asking Claude to analyze images, generate embeddings for semantic search, or run detection on your photos.

Sample workflows you might run include: Show me all images with cars detected, Find documents mentioning "AI", Create a summary of this video.

New Features

Configurable datastore path lets you decide where Pixeltable stores its data. You can set and get the datastore path with natural language prompts.

Interactive Python REPL provides a persistent session with Pixeltable pre-loaded so you can experiment with functions and introspection.

Bug logging and testing enable structured logs for issues, missing features, and successful changes. You can generate a bug report to summarize all issues found during testing.

Troubleshooting

Claude Desktop issues: restart Claude Desktop after adding the MCP server, verify the Pixeltable home path, ensure you are using the latest Claude Desktop, and confirm uv is installed and on your PATH.

Cursor issues: ensure MCP support is enabled, restart Cursor after changes, and check logs for errors.

Installation issues: confirm Python 3.10+, ensure uv is installed, and try installing from source if the standard path fails.

Getting help: use the built-in bug logging prompts, generate a bug report, or file an issue on the project’s repository.

Available tools

execute_python

Execute Python code with Pixeltable pre-loaded in a persistent session.

introspect_function

Get docs and signature for a Pixeltable function.

list_available_functions

Discover available Pixeltable functions and their usage.

log_bug

Record a bug with details such as severity and function involved for later review.

log_missing_feature

Log missing features with a use case to guide future development.

log_success

Log successful operations with context to help QA and tracing.

generate_bug_report

Produce a summary report of logged bugs and issues.