Pixeltable MCP 서버 (개발자 에디션)

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

MCP 서버 형태의 멀티모달 AI 데이터 인프라입니다. 테이블 관리, AI/ML 파이프라인, 의존성 관리, 대화형 REPL 등을 위한 32개의 도구 · 13개의 리소스 · 6개의 프롬프트를 제공합니다.

Pixeltable 0.5.27 이상에서 최상의 성능을 위해 sync 엔드포인트 + uvloop를 사용합니다 (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 없이도 도구를 호출하고, 리소스를 읽고, 프롬프트를 테스트할 수 있게 합니다.

빠른 확인: openai.chat_completions 표현식을 사용하는 pixeltable_check_dependencies 도구; print(pxt.__version__)을 사용하는 execute_python 도구; 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/로깅 도우미 제외). 전체 독스트링은 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 vs 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)