Pixeltable MCP Server (Developer Edition)

⚠️ WARNING: THIS IS AN EXPERIMENTAL DEVELOPMENT TOOL. DO NOT USE WITH IMPORTANT DATA. THIS IS FOR DEMO PURPOSES ONLY UNTIL FURTHER NOTICE.

Claude meets Pixeltable. Multimodal AI data infrastructure - not (just) a database - now available as an MCP server.

⚡ Quick Start

Prerequisites

You must have uv installed. If you don't have it or aren't sure, run:

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

Or consult the uv installation guide.

Claude Code Installation (Easiest!)

Just tell Claude:

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

That's it! Claude will handle the installation and configuration for you.

Manual Installation with uv tool

# Install as a global tool
uv tool install --from git+https://github.com/pixeltable/mcp-server-pixeltable-developer.git mcp-server-pixeltable-developer

# 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

Installation from source (For development)

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

Configuration for Claude Desktop

⚠️ Note: If you experience issues with Claude Desktop configuration, you may need to restart Claude Desktop after adding the MCP server configuration.

Add to your Claude Desktop config:

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

Or if running from source:

{
  "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 .cursorrules file or configure it through Cursor's MCP settings:

1. Via Cursor Settings:

   • Open Cursor Settings
   • Navigate to "Features" → "Model Context Protocol"
   • Add a new MCP server with command: mcp-server-pixeltable-developer

2. Via JSON Configuration: Add to your Cursor MCP configuration:

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

3. For development/source installations:

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

Claude: Create a table for my screenshots
Claude: Add object detection to all images
Claude: Transcribe any audio files with Whisper

Local AI analysis:

Claude: Use Ollama to analyze these images
Claude: Generate embeddings for semantic search
Claude: Run YOLOX object detection on my photos

Data workflows:

Claude: Show me all images with cars detected
Claude: Find documents mentioning "AI"
Claude: Create a summary of this video

🚀 New Features

Configurable Datastore Path

Change where Pixeltable stores its data:

Claude: Set datastore to ~/my-pixeltable-data
Claude: Get current datastore configuration

The datastore path can be configured through:

1. Environment variable PIXELTABLE_HOME (highest priority)
2. Persistent configuration file (survives restarts)
3. System default ~/.pixeltable

Interactive Python REPL

Execute Python code with PixelTable pre-loaded in a persistent session:

Claude: execute_python("tables = pxt.list_tables(); print(f'Found {len(tables)} tables')")
Claude: introspect_function("pxt.create_table")  # Get docs and signature
Claude: list_available_functions("pxt")          # Discover PixelTable functions

Bug Logging & Testing

Structured logging for testing and bug discovery:

Claude: log_bug("Cannot save images", severity="high", function_name="pxt.create_table")
Claude: log_missing_feature("No image resize function", use_case="Standardize image sizes")
Claude: log_success("Table creation works", approach="Used schema parameter")
Claude: generate_bug_report()  # Get summary of all issues

Bug logs are saved to pixeltable_testing_logs/ in both Markdown and JSON formats.

Why These Features?

• REPL: Explore PixelTable dynamically without rebuilding the MCP
• Introspection: Discover functions and get docs on-demand
• Bug Logging: Document issues systematically during development
• Future-proof: Adapts to PixelTable API changes automatically

---

🔧 Troubleshooting

Claude Desktop Issues

If you're having trouble with Claude Desktop:

1. Restart Claude Desktop after adding the MCP server configuration
2. Check that the path to your Pixeltable home directory is correct
3. Ensure you have the latest version of Claude Desktop
4. Verify that uv is installed and accessible from your PATH

Cursor Issues

If Cursor isn't recognizing the MCP server:

1. Make sure you have MCP support enabled in Cursor settings
2. Restart Cursor after configuration changes
3. Check the Cursor logs for any error messages

Installation Issues

If installation fails:

1. Ensure you have Python 3.10+ installed
2. Make sure uv is installed: curl -LsSf https://astral.sh/uv/install.sh | sh
3. Try installing from source if the GitHub installation fails

Getting Help

If you encounter issues:

1. Use the built-in bug logging: Claude: log_bug("description", severity="high")
2. Check the generated bug report: Claude: generate_bug_report()
3. File an issue on the GitHub repository

---

Built while having coffee. ☕