Pixeltable MCP 服务器（开发者版）

Name: Pixeltable MCP Server (Developer Edition)
Author: pixeltable

作为 MCP 服务器的多模态 AI 数据基础设施。32 个工具 · 13 个资源 · 6 个提示词，用于表管理、AI/ML 流水线、依赖管理、交互式 REPL 等。

使用 sync 端点 + uvloop 以获得 Pixeltable ≥ 0.5.27 的最佳性能（参见 pyproject.toml）。

快速开始

需要 uv：

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

Claude Code（最简单） — 只需说：

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

手动安装：

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

如果 uv 警告 ~/.local/bin 不在你的 PATH 中，请运行 uv tool update-shell（或将该目录添加到 PATH），以便找到 mcp-server-pixeltable-developer。使用 mcp-server-pixeltable-developer --version 进行检查。

从源码安装：

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

客户端配置

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

从源码安装 — 使用 "command": "uv" 和 "args": ["run", "--directory", "{repo}", "python", "-m", "mcp_server_pixeltable_stio"]。

用户配置 — ~/.cursor/mcp.json（适用于所有工作区）：

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

如果 Cursor 报告 command not found，请使用 uv tool update-shell / which mcp-server-pixeltable-developer 提供的完整路径，例如 "command": "/Users/you/.local/bin/mcp-server-pixeltable-developer"。

从源码开发此仓库 — 可选的项目 .cursor/mcp.json，以便服务器从你的克隆版本运行（替换路径）：

{
  "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"
      }
    }
  }
}

除非你打算运行两个条目，否则不要定义两次相同的服务器名称（用户 + 项目）。

配置更改后请重启你的客户端。

测试

使用专用的 PIXELTABLE_HOME 进行测试，以免影响其他目录。

MCP Inspector（交互式）

从克隆版本中，在 uv sync 之后：

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

这将启动服务器并在浏览器中打开 MCP Inspector，这样你无需 IDE 即可调用工具、读取资源并尝试提示词。

快速检查： 工具 pixeltable_check_dependencies，表达式为 openai.chat_completions；工具 execute_python，内容为 print(pxt.__version__)；资源 pixeltable://version。

Cursor

在 .cursor/mcp.json 的 env 下添加 PIXELTABLE_HOME（参见上方的客户端配置）。重启 Cursor，确认服务器已连接，然后从 MCP 面板运行一个简单的工具。

CLI 健全性检查（无 JSON-RPC）

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

--version / --help 会立即退出。list_tools.py 仅打印已注册的工具、资源和提示词（导入检查，非完整的 MCP 会话）。

工具 (32)

类别	工具
表	`create_table` · `drop_table` · `create_view` · `create_snapshot`
数据	`create_replica` · `query_table` · `insert_data` · `query` · `add_computed_column`
目录	`create_dir` · `drop_dir` · `move`
配置	`configure_logging` · `set_datastore`
AI/ML	`create_udf` · `create_array` · `create_tools` · `connect_mcp`
依赖	`check_dependencies` · `install_dependency`
类型	`create_type` (Image, Video, Audio, Array[Float], …)
文档	`search_docs`
REPL	`execute_python` · `introspect_function` · `list_available_functions` · `install_package`
日志	`log_bug` · `log_missing_feature` · `log_success` · `generate_bug_report` · `get_session_summary`
显示	`display_in_browser`

所有工具均以 pixeltable_ 为前缀（REPL/日志辅助工具除外）。完整的 docstrings 可通过 introspect_function 获取。

资源 (13)

URI	返回内容
`pixeltable://tables`	所有表及其计数
`pixeltable://tables/{path}`	关于表/视图/快照的信息
`pixeltable://tables/{path}/schema`	列模式
`pixeltable://directories`	所有目录
`pixeltable://ls` / `pixeltable://ls/{path}`	目录列表
`pixeltable://version`	Pixeltable 版本
`pixeltable://config/datastore`	数据存储配置
`pixeltable://types`	可用数据类型
`pixeltable://functions`	已注册的 Pixeltable 函数
`pixeltable://tools`	MCP 工具列表
`pixeltable://help`	工作流指南
`pixeltable://diagnostics`	系统和依赖诊断

提示词 (6)

pixeltable_usage_guide · getting_started · computer_vision_pipeline · rag_pipeline · video_analysis_pipeline · audio_processing_pipeline

示例

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())")

文档

Pixeltable 文档
pixeltable-skill — 任务路由、API 陷阱（openai.vision 与 chat_completions、frame_iterator、similarity(string=...) 等）以及与当前 Pixeltable 一致的工作流示例

架构

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

故障排除

配置更改后重启你的客户端
需要 Python 3.10+ 和 uv
uv tool install 后出现 command not found：确保 ~/.local/bin 在 PATH 中（uv tool update-shell）或通过完整路径调用；使用 mcp-server-pixeltable-developer --version 进行确认
检查 PIXELTABLE_HOME 是否指向有效的目录
使用 log_bug(...) / generate_bug_report() 进行结构化问题跟踪
在 github.com/pixeltable/mcp-server-pixeltable-developer 提交问题

Pixeltable MCP Server (Developer Edition)