Pixeltable MCP Server (Developer Edition)

Multimodal AI data infrastructure as an MCP server. 32 tools · 13 resources · 6 prompts for table management, AI/ML pipelines, dependency management, an interactive REPL, and more.

Uses sync endpoints + uvloop for best performance with Pixeltable ≥ 0.5.27 (see pyproject.toml).

Quick Start

Requires uv:

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

Claude Code (easiest) — just say:

"Install https://github.com/pixeltable/mcp-server-pixeltable-developer as a uv tool and add it to your MCPs"

Manual install:

uv tool install --from git+https://github.com/pixeltable/mcp-server-pixeltable-developer.git mcp-server-pixeltable-developer
claude mcp add pixeltable mcp-server-pixeltable-developer   # Claude Code

If uv warns that ~/.local/bin is not on your PATH, run uv tool update-shell (or add that directory to PATH) so mcp-server-pixeltable-developer is found. Check with mcp-server-pixeltable-developer --version.

From source:

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

Client Configuration

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

From source — use "command": "uv" with "args": ["run", "--directory", "{repo}", "python", "-m", "mcp_server_pixeltable_stio"].

User config — ~/.cursor/mcp.json (applies to all workspaces):

{
  "mcpServers": {
    "pixeltable-developer": {
      "command": "mcp-server-pixeltable-developer",
      "env": {
        "PIXELTABLE_HOME": "/Users/you/.pixeltable"
      }
    }
  }
}

If Cursor reports command not found, use the full path from uv tool update-shell / which mcp-server-pixeltable-developer, e.g. "command": "/Users/you/.local/bin/mcp-server-pixeltable-developer".

Develop this repo from source — optional project .cursor/mcp.json so the server runs from your clone (replace the path):

{
  "mcpServers": {
    "pixeltable-developer": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server-pixeltable-developer", "python", "-m", "mcp_server_pixeltable_stio"],
      "env": {
        "PIXELTABLE_HOME": "/Users/you/.pixeltable"
      }
    }
  }
}

Do not define the same server name twice (user + project) unless you intend to run two entries.

Restart your client after configuration changes.

Testing

Use a dedicated PIXELTABLE_HOME for testing so you do not touch other catalogs.

MCP Inspector (interactive)

From a clone, after uv sync:

export PIXELTABLE_HOME="$HOME/.pixeltable-mcp-test"
uv run mcp dev src/mcp_server_pixeltable_stio/server.py:mcp

This starts the server and opens the MCP Inspector in your browser so you can invoke tools, read resources, and try prompts without an IDE.

Quick checks: tool pixeltable_check_dependencies with expression openai.chat_completions; tool execute_python with print(pxt.__version__); resource pixeltable://version.

Cursor

Add PIXELTABLE_HOME under env in .cursor/mcp.json (see Client Configuration above). Restart Cursor, confirm the server connects, then run a simple tool from the MCP panel.

CLI sanity (no JSON-RPC)

mcp-server-pixeltable-developer --version
uv run python list_tools.py

--version / --help exit immediately. list_tools.py only prints registered tools, resources, and prompts (import check, not a full MCP session).

Tools (32)

All tools are prefixed pixeltable_ (except REPL/logging helpers). Full docstrings available via introspect_function.

Resources (13)

Prompts (6)

pixeltable_usage_guide · getting_started · computer_vision_pipeline · rag_pipeline · video_analysis_pipeline · audio_processing_pipeline

Examples

Create a table called movies with title, year, and rating columns → insert sample data → query ratings above 8.5

Add a computed column that runs YOLOX object detection on every image

Check what deps I need for openai.chat_completions(...) → install them

execute_python("print(pxt.list_tables())")

Documentation

• Pixeltable docs

• pixeltable-skill — task router, API pitfalls (openai.vision vs chat_completions, frame_iterator, similarity(string=...), etc.), and workflow examples aligned with current Pixeltable

Architecture

src/mcp_server_pixeltable_stio/
  server.py            FastMCP server, tool/resource/prompt registration, uvloop activation
  core/
    tables.py          Table CRUD, views, snapshots, replicas, queries, computed columns
    directories.py     Directory CRUD, listing, moving
    dependencies.py    Dependency checking, unified installer, diagnostics
    udf.py             UDF creation, type system, LLM tool wrappers, MCP connections
    helpers.py         Config, version, docs search, shared utilities
    resources.py       Read-only MCP resource handlers
  prompt.py            Prompt templates for common workflows
  repl_functions.py    Persistent Python REPL, introspection, package management
  canvas_server.py     Browser canvas for rich content display

Troubleshooting

• Restart your client after any config change

• Python 3.10+ and uv are required

• command not found after uv tool install: ensure ~/.local/bin is on PATH (uv tool update-shell) or invoke via full path; confirm with mcp-server-pixeltable-developer --version

• Check that PIXELTABLE_HOME points to a valid directory

• Use log_bug(...) / generate_bug_report() for structured issue tracking

• File issues at github.com/pixeltable/mcp-server-pixeltable-developer