Pixeltable Developer MCP Server

A local Model Context Protocol server for building, inspecting, and operating Pixeltable applications. Version 0.2 follows the application-first workflow in pixeltable-skill 2.12.0: generate one app.py, apply its schema, and serve its routes with the pxt CLI.

Compatibility

The server is a beta developer tool. It runs with the permissions of the process that launched it and can mutate the selected Pixeltable catalog. Point PIXELTABLE_MCP_PROJECT_ROOT at the application directory and PIXELTABLE_HOME at the intended catalog before startup. Both locations are fixed for the life of the process. Use a separate catalog for evaluation and automated tests.

Install and connect

Install uv, then run the server from PyPI:

uvx mcp-server-pixeltable-developer --version

For reproducible development from a clone:

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

The repository also builds a container image that runs the same stdio server. Mount your application directory and point both variables at the mounts; the catalog is lost with the container unless you mount one too. On macOS, the host paths must be shared with your container engine, or the mount lands inside its VM:

docker build -t mcp-server-pixeltable-developer .
docker run --rm -i \
  -e PIXELTABLE_MCP_PROJECT_ROOT=/work/app -e PIXELTABLE_HOME=/work/catalog \
  -v /absolute/path/to/pixeltable-app:/work/app \
  -v /absolute/path/to/.pixeltable:/work/catalog \
  mcp-server-pixeltable-developer

Configure a client to launch the server over stdio. Replace the application project and catalog paths with absolute paths:

{
  "mcpServers": {
    "pixeltable": {
      "command": "uvx",
      "args": ["mcp-server-pixeltable-developer"],
      "env": {
        "PIXELTABLE_MCP_PROJECT_ROOT": "/absolute/path/to/pixeltable-app",
        "PIXELTABLE_HOME": "/absolute/path/to/.pixeltable"
      }
    }
  }
}

Claude Code:

claude mcp add pixeltable -e PIXELTABLE_MCP_PROJECT_ROOT=/absolute/path/to/pixeltable-app -e PIXELTABLE_HOME=/absolute/path/to/.pixeltable -- uvx mcp-server-pixeltable-developer

To run a clone instead, use "command": "uv" with "args": ["run", "--directory", "/absolute/path/to/mcp-server-pixeltable-developer", "mcp-server-pixeltable-developer"].

Restart the client after changing its MCP configuration. Keep one server process per catalog when performing schema or service mutations.

The pxt CLI talks to one local daemon per port (22089 by default), and a pxt command from a different project root restarts that daemon. If you run pxt for another project while the server is working, its calls can fail with RemoteDisconnected. Give the server its own port by adding "PXT_PORT": "22090" (any free port) to env.

Default interface

Version 0.2 exposes a focused interface instead of mirroring the whole Pixeltable Python API.

Tools

Read tools declare read-only MCP annotations. Mutation tools declare their write and destructive behavior. Arguments and results use typed schemas, and recoverable failures are returned as MCP tool errors so clients can retry with corrected input.

Resources

Prompts

• pixeltable_build_app
• pixeltable_build_rag
• pixeltable_build_agent
• pixeltable_debug_computation

The prompts are short task guides aligned with pixeltable-skill 2.12.0. The skill remains the detailed source for provider output shapes, multimodal views, indexes, tool calling, serving, debugging, and Cloud workflows.

Unsafe mode

Host-code execution, package installation, and browser display are disabled by default. A trusted local user can opt in before starting the server:

export PIXELTABLE_MCP_ENABLE_UNSAFE=1

This adds:

• pixeltable_unsafe_execute_python
• pixeltable_unsafe_install_package
• pixeltable_unsafe_display

These tools are available only on stdio. They can execute arbitrary Python, change the server environment, read files available to the server process, and render untrusted content. Enable them only for a trusted, local MCP client and a disposable development environment. Do not expose unsafe mode through an HTTP transport.

The repository may use an in-process or HTTP harness in tests. HTTP is not a supported production transport for version 0.2. A future HTTP release must add authorization, concurrency and request limits, origin and host validation, per-principal isolation, and an explicit threat model before it is supported.

Recommended Pixeltable workflow

Start an application with the current Pixeltable CLI:

pip install 'pixeltable[serve]>=0.7.10,<0.8'
pxt init
pxt service example --out app.py
pxt schema check app.py
pxt schema diff app.py my_app
pxt schema update app.py my_app
pxt service check app.py
pxt service update app.py my_app
pxt service list

my_app is a catalog directory. It is not a filesystem directory. Edit app.py and apply the schema again when the model changes. Apply the service again after route changes. Use pxt service list to discover the assigned URL.

The application file should declare TableModel classes and, when HTTP routes are needed, a FastAPIRouter. Stored columns use annotations. Computed columns use assignments. Types are non-nullable by default; write T | None for an optional column. Do not use pxt.Required.

Schema updates intentionally require a review step. schema_check validates the file, schema_diff previews catalog changes, and schema_update applies them. Prune operations are separate because they can remove catalog objects. To change a computed-column expression, edit it and apply the schema again: the update keeps existing values, so run pxt recompute my_app/docs COLUMN -f to refresh them. Changing a column's type is unsupported in place; rename a computed column instead.

For Cloud, prepare the same app.py, sign in with pxt login (or set PIXELTABLE_API_KEY), declare the target pxt://org:db in pixeltable.toml, and review pixeltable://guidance/cloud. The MCP server does not create paid resources or deploy to Cloud automatically.

Develop and verify

Use a disposable catalog:

export PIXELTABLE_MCP_PROJECT_ROOT="$PWD"
export PIXELTABLE_HOME="$(mktemp -d)/catalog"
uv sync --frozen --extra test
uv run pytest -q
PIXELTABLE_DISABLE_STDOUT=1 uv run pytest --run-slow -q
uv run python list_tools.py
./scripts/run-conformance.sh
./scripts/build-mcpb.sh

build-mcpb.sh writes the desktop-extension bundle to dist/ from tracked files only. Pushing a v* tag publishes to PyPI through trusted publishing once the test, quality, bounds, conformance, and evaluation-artifact jobs pass; register this repository, workflow ci.yml, and environment pypi as a trusted publisher on PyPI one time before the first tag.

Run the MCP Inspector only as a local test harness:

uv run mcp dev src/mcp_server_pixeltable_developer/server.py:mcp

Before release, also run the latest-dependency compatibility job, the MCP in-memory contract tests, the subprocess stdio smoke test, lint, type checks, and package build verification described in the review report.

Privacy Policy

The server runs entirely on the machine that starts it. It collects no telemetry and no analytics, and it sends nothing to Pixeltable or to any third party.

What it handles. The Pixeltable catalog at PIXELTABLE_HOME and the application files under PIXELTABLE_MCP_PROJECT_ROOT, both chosen by you. Tool results are returned to the MCP client that launched the server, which is how your assistant reads them. Nothing else receives them.

Storage and retention. The server stores nothing of its own. Catalog data stays in PIXELTABLE_HOME on your disk, under your control, and is removed when you remove it.

Secrets. Command output is passed through a redactor that masks common credential forms, including URL passwords and API tokens, before it reaches the client.

Third parties. If your application declares computed columns that call model providers, Pixeltable makes those calls with the credentials you configured. That traffic is your application's, not this server's.

Unsafe mode. With PIXELTABLE_MCP_ENABLE_UNSAFE=1, the added tools execute arbitrary Python, install packages, and read files available to the server process. Enable it only on a trusted local machine.

Contact. Report privacy questions through GitHub issues.

Documentation

• 0.1.0 evidence review
• 0.2.0 implementation review
• Migration from 0.1 to 0.2
• Agent evaluation protocol
• Pixeltable documentation
• Pixeltable get started
• Pixeltable LLM reference
• MCP Python SDK 2 documentation

License

Apache-2.0. See LICENSE.