# loom-mcp

MCP server for Loom video management. Provides tools to list, retrieve, edit, and merge Loom screen recordings.

## Features

- **list_recorded_videos** - Retrieve a list of recorded videos with pagination and folder filtering
- **get_video** - Get detailed information about a specific video
- **edit_video** - Edit videos by trimming or extracting clips
- **merge_videos** - Combine multiple videos into one

## Installation

```bash
# Clone or download the package
cd loom-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"
```

## Configuration

Create a `.env` file based on `.env.example`:

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

Required environment variables:

| Variable | Description |
|----------|-------------|
| `LOOM_ACCESS_TOKEN` | OAuth2 access token for Loom API |

Optional environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `LOOM_BASE_URL` | Loom API base URL | `https://api.loom.com/v1` |

### Getting an Access Token

Loom uses OAuth2 for authentication. To obtain an access token:

1. Register your application in the [Loom Developer Portal](https://dev.loom.com)
2. Implement the OAuth2 authorization flow
3. Use the returned access token in your configuration

**Note:** Loom's public API access may be limited. Enterprise users may have additional API capabilities. Contact Loom for API access details.

## Usage with Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "loom": {
      "command": "/path/to/loom-mcp/venv/bin/python",
      "args": ["-m", "loom_mcp.server"],
      "env": {
        "LOOM_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}
```

## Tools

### list_recorded_videos

Retrieve a list of recorded videos from Loom.

**Parameters:**
- `limit` (optional): Maximum number of videos to return (1-100, default 50)
- `offset` (optional): Pagination offset (default 0)
- `folder_id` (optional): Filter videos by folder ID

**Example:**
```json
{
  "limit": 10,
  "offset": 0,
  "folder_id": "folder-abc"
}
```

### get_video

Retrieve detailed information about a specific video.

**Parameters:**
- `video_id` (required): Unique identifier for the video

**Example:**
```json
{
  "video_id": "abc123"
}
```

### edit_video

Edit a video by adding clips or trimming sections.

**Parameters:**
- `video_id` (required): Unique identifier for the video
- `editing_details` (required): Object containing edit instructions
  - `trim_start`: Start time in seconds to trim from beginning
  - `trim_end`: End time in seconds where video should end
  - `clips`: List of clip objects with `start` and `end` times
  - `title`: Optional new title for the edited video
  - `description`: Optional new description

**Example:**
```json
{
  "video_id": "abc123",
  "editing_details": {
    "trim_start": 5,
    "trim_end": 120,
    "title": "Edited Demo"
  }
}
```

### merge_videos

Combine multiple videos into one merged video.

**Parameters:**
- `video_ids` (required): List of video IDs to merge (minimum 2, in order)
- `title` (optional): Title for the merged video

**Example:**
```json
{
  "video_ids": ["video-1", "video-2", "video-3"],
  "title": "Combined Demo"
}
```

## Development

### Running Tests

```bash
# Activate virtual environment
source venv/bin/activate

# Run tests
pytest

# Run with coverage
pytest --cov=loom_mcp --cov-report=term-missing
```

### Code Quality

```bash
# Format and lint
ruff check src tests
ruff format src tests

# Type checking
mypy src
```

## Project Structure

```
loom-mcp/
├── src/
│   └── loom_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server entry point
│       ├── clients/
│       │   ├── __init__.py
│       │   └── loom.py        # Loom API client
│       └── tools/
│           ├── __init__.py
│           ├── list_recorded_videos.py
│           ├── get_video.py
│           ├── edit_video.py
│           └── merge_videos.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_loom_client.py
│   ├── test_tools.py
│   └── test_server.py
├── pyproject.toml
├── README.md
└── .env.example
```

## License

MIT

---

Generated by GRIMLOCK MCP Factory
