# picsellia-mcp

An [MCP](https://modelcontextprotocol.io) server that wraps the [Picsellia](https://www.picsellia.com) Python SDK, giving AI assistants access to your computer vision platform — datasets, experiments, models, deployments, and monitoring.

## Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/)
- A Picsellia account with an API token

## Installation

```bash
git clone <repo-url>
cd picsellia-mcp
uv sync
```

## Configuration

Copy the example env file and fill in your credentials:

```bash
cp .env.example .env
```

| Variable | Required | Default | Description |
|---|---|---|---|
| `PICSELLIA_API_TOKEN` | Yes | — | Your Picsellia API token |
| `PICSELLIA_ORGANIZATION_NAME` | No | `None` | Organization to connect to |
| `PICSELLIA_HOST` | No | `https://app.picsellia.com` | Picsellia API host |
| `MCP_TRANSPORT` | No | `stdio` | Transport protocol (`stdio` or `streamable-http`) |

## Usage

### Claude Desktop

Add the following to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "picsellia": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/picsellia-mcp",
        "picsellia-mcp"
      ],
      "env": {
        "PICSELLIA_API_TOKEN": "<your-token>",
        "PICSELLIA_ORGANIZATION_NAME":"",
        "PICSELLIA_HOST":"https://app.picsellia.com",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

> If `uv` is not on your PATH, use the absolute path (e.g. `~/.local/bin/uv`).

### Claude Code

Add the server from the project directory:

```bash
claude mcp add picsellia -- uv run --directory /absolute/path/to/picsellia-mcp picsellia-mcp
```

Or add it to `.claude/settings.json` directly:

```json
{
  "mcpServers": {
    "picsellia": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/picsellia-mcp",
        "picsellia-mcp"
      ],
      "env": {
        "PICSELLIA_API_TOKEN": "<your-token>",
        "PICSELLIA_ORGANIZATION_NAME":"",
        "PICSELLIA_HOST":"https://app.picsellia.com",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

### Cursor

Open **Settings > MCP** and add a new server:

```json
{
  "mcpServers": {
    "picsellia": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/picsellia-mcp",
        "picsellia-mcp"
      ],
      "env": {
        "PICSELLIA_API_TOKEN": "<your-token>",
        "PICSELLIA_ORGANIZATION_NAME":"",
        "PICSELLIA_HOST":"https://app.picsellia.com",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

### Standalone (stdio)

```bash
uv run picsellia-mcp
```

### Standalone (HTTP)

```bash
MCP_TRANSPORT=streamable-http uv run picsellia-mcp
```

## Available Tools

53 tools organized by domain:

| Category | Tools | Description |
|---|---|---|
| **Datasets** | 9 | List, get, browse versions, assets, labels, stats |
| **Projects** | 8 | List, create, get projects; list experiments |
| **Models** | 6 | List, get models and versions; list files |
| **Experiments** | 6 | Create, launch, attach/detach datasets, set base model |
| **Datalakes** | 4 | List datalakes, browse data items and tags |
| **Deployments** | 9 | List, get deployments; monitoring stats; predicted assets |
| **Logs** | 4 | List, get, filter, and compare experiment logs |
| **Annotations** | 3 | Get annotations, search assets with query language |
| **Evaluations** | 4 | List evaluations and artifacts |

Most tools are read-only. Write operations are limited to experiment management (create, launch, attach datasets, set base model).