npm package: @jclvsh/dropspace
Description: MCP server and CLI for the Dropspace API
Latest version: 2.0.0

# @jclvsh/dropspace

MCP server and CLI for the [Dropspace](https://dropspace.dev) API. Lets AI agents (Claude Code, Cursor) and humans manage launches, personas, platform connections, API keys, and webhooks.

## Installation

```bash
npx @jclvsh/dropspace
```

Or install globally:

```bash
npm install -g @jclvsh/dropspace
```

## Configuration

### Environment Variables

| Variable            | Required | Description                                         |
| ------------------- | -------- | --------------------------------------------------- |
| `DROPSPACE_API_KEY` | Yes      | Your Dropspace API key                              |
| `DROPSPACE_API_URL` | No       | API base URL (default: `https://api.dropspace.dev`) |

### Claude Code

Add to your `.claude/settings.json`:

```json
{
	"mcpServers": {
		"dropspace": {
			"command": "npx",
			"args": ["-y", "@jclvsh/dropspace"],
			"env": {
				"DROPSPACE_API_KEY": "ds_live_your_key_here"
			}
		}
	}
}
```

### Cursor

Add to your `.cursor/mcp.json`:

```json
{
	"mcpServers": {
		"dropspace": {
			"command": "npx",
			"args": ["-y", "@jclvsh/dropspace"],
			"env": {
				"DROPSPACE_API_KEY": "ds_live_your_key_here"
			}
		}
	}
}
```

## Available Tools

### Launches

| Tool                   | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `list_launches`        | List your launches with pagination                             |
| `create_launch`        | Create a new launch with content, media, and account selection |
| `get_launch`           | Get a launch by ID with posting status                         |
| `update_launch`        | Update a launch's schedule, status, content, or media          |
| `delete_launch`        | Delete a launch                                                |
| `publish_launch`       | Publish a launch to all configured platforms                   |
| `retry_launch`         | Retry failed platforms for a launch                            |
| `generate_content`     | Generate AI content and video scripts for a launch             |
| `retry_launch_content` | Retry AI content generation for failed platforms               |
| `get_launch_analytics` | Get publishing analytics with per-post engagement metrics      |
| `get_launch_status`    | Get detailed posting status with per-platform logs             |

#### `create_launch` Parameters

| Parameter                     | Type               | Required | Description                                                                                                                                                                                             |
| ----------------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                       | string             | Yes      | Launch title                                                                                                                                                                                            |
| `product_description`         | string             | Yes      | Product description                                                                                                                                                                                     |
| `platforms`                   | string[]           | Yes      | Platforms to publish to (1-9)                                                                                                                                                                           |
| `product_url`                 | string             | No       | Product URL                                                                                                                                                                                             |
| `scheduled_date`              | string             | No       | ISO 8601 datetime (15+ min in the future)                                                                                                                                                               |
| `persona_id`                  | string             | No       | Persona ID for tone/style                                                                                                                                                                               |
| `dropspace_platforms`         | string[]           | No       | Platforms to post via official dropspace accounts                                                                                                                                                       |
| `media_mode`                  | string             | No       | `"images"` or `"video"`                                                                                                                                                                                 |
| `user_platform_accounts`      | object             | No       | Map of platform key to token_id (UUID). Simple keys: `twitter`, `reddit`, `instagram`, `tiktok`. LinkedIn: `linkedin:personal` or `linkedin:organization:<org_id>`. Facebook: `facebook:page:<page_id>` |
| `platform_contents`           | object             | No       | Per-platform content (mutually exclusive with `custom_content`)                                                                                                                                         |
| `custom_content`              | string \| string[] | No       | Single content for all platforms, or array of tweets for twitter thread mode (mutually exclusive with `platform_contents`)                                                                              |
| `custom_content_reddit_title` | string             | No       | Reddit title (required with `custom_content` + reddit)                                                                                                                                                  |
| `media`                       | object[]           | No       | Inline media, URL or base64 (1-10 items, mutually exclusive with `media_assets`)                                                                                                                        |
| `media_assets`                | object[]           | No       | Pre-uploaded media references (mutually exclusive with `media`)                                                                                                                                         |
| `media_attach_platforms`      | string[]           | No       | Platforms to attach media to                                                                                                                                                                            |
| `generate_ai_videos`          | string[]           | No       | Auto-generate AI videos (`"instagram"`, `"tiktok"`)                                                                                                                                                     |

#### `update_launch` Parameters

| Parameter                | Type           | Required | Description                                                                                                                                                                                             |
| ------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | string         | Yes      | Launch ID                                                                                                                                                                                               |
| `scheduled_date`         | string \| null | No       | ISO 8601 datetime or null to clear                                                                                                                                                                      |
| `status`                 | string         | No       | `"draft"`, `"manual"`, `"trigger"`, `"scheduled"`, `"cancelled"`                                                                                                                                        |
| `platform_contents`      | object         | No       | Per-platform content overrides                                                                                                                                                                          |
| `dropspace_platforms`    | string[]       | No       | Official dropspace account platforms                                                                                                                                                                    |
| `user_platform_accounts` | object         | No       | Map of platform key to token_id (UUID). Simple keys: `twitter`, `reddit`, `instagram`, `tiktok`. LinkedIn: `linkedin:personal` or `linkedin:organization:<org_id>`. Facebook: `facebook:page:<page_id>` |
| `media`                  | object[]       | No       | Inline media (URL or base64, 1-10 items)                                                                                                                                                                |
| `media_assets`           | object[]       | No       | Pre-uploaded media references                                                                                                                                                                           |
| `media_attach_platforms` | string[]       | No       | Platforms to attach media to                                                                                                                                                                            |
| `media_mode`             | string         | No       | `"images"` or `"video"`                                                                                                                                                                                 |

#### `generate_content` Parameters

| Parameter                | Type     | Required | Description                                                         |
| ------------------------ | -------- | -------- | ------------------------------------------------------------------- |
| `id`                     | string   | Yes      | Launch ID                                                           |
| `platforms`              | string[] | No       | Platforms to generate for (defaults to all)                         |
| `generate_video_scripts` | string[] | No       | Platforms to generate video scripts for (`"instagram"`, `"tiktok"`) |

### Personas

| Tool              | Description                                      |
| ----------------- | ------------------------------------------------ |
| `list_personas`   | List your personas                               |
| `create_persona`  | Create a new persona for content tone/style      |
| `get_persona`     | Get a persona by ID with analysis details        |
| `update_persona`  | Update a persona's name or writing samples       |
| `delete_persona`  | Delete a persona                                 |
| `analyze_persona` | Trigger AI analysis of a persona's writing style |

#### `analyze_persona` Parameters

| Parameter                | Type          | Required | Description                                |
| ------------------------ | ------------- | -------- | ------------------------------------------ |
| `id`                     | string (UUID) | Yes      | Persona ID                                 |
| `platforms`              | string[]      | No       | Specific platforms to analyze samples from |
| `include_custom_samples` | boolean       | No       | Include custom writing samples in analysis |

#### `update_persona` Parameters

| Parameter           | Type   | Required | Description                         |
| ------------------- | ------ | -------- | ----------------------------------- |
| `id`                | string | Yes      | Persona ID                          |
| `name`              | string | No       | New persona name (1-100 characters) |
| `custom_samples`    | array  | No       | Custom writing samples (max 50)     |
| `twitter_samples`   | array  | No       | Twitter writing samples (max 50)    |
| `reddit_samples`    | array  | No       | Reddit writing samples (max 50)     |
| `facebook_samples`  | array  | No       | Facebook writing samples (max 50)   |
| `instagram_samples` | array  | No       | Instagram writing samples (max 50)  |
| `tiktok_samples`    | array  | No       | TikTok writing samples (max 50)     |
| `linkedin_samples`  | array  | No       | LinkedIn writing samples (max 50)   |

### Connections

| Tool               | Description                               |
| ------------------ | ----------------------------------------- |
| `list_connections` | List your connected social media accounts |

### Posts

| Tool               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `delete_post`      | Delete a single published post from its platform       |
| `delete_all_posts` | Delete all published posts for a launch from platforms |

### API Keys

| Tool                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `get_current_api_key` | Get the current API key's info (no scope required) |
| `list_api_keys`       | List your API keys (requires admin scope)          |
| `create_api_key`      | Create a new API key (raw key returned once)       |
| `rename_api_key`      | Rename an API key                                  |
| `revoke_api_key`      | Permanently revoke an API key                      |

#### `create_api_key` Parameters

| Parameter | Type     | Required | Description                                                                                    |
| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------- |
| `name`    | string   | Yes      | Key name (1-100 characters)                                                                    |
| `scopes`  | string[] | No       | Permission scopes (defaults to all): `read`, `write`, `delete`, `publish`, `generate`, `admin` |

### Webhooks

| Tool                      | Description                                                  |
| ------------------------- | ------------------------------------------------------------ |
| `list_webhooks`           | List your webhooks                                           |
| `create_webhook`          | Create a webhook endpoint (secret returned once)             |
| `get_webhook`             | Get a webhook by ID                                          |
| `update_webhook`          | Update a webhook's URL, events, or active status             |
| `delete_webhook`          | Delete a webhook                                             |
| `rotate_webhook_secret`   | Rotate a webhook's signing secret (new secret returned once) |
| `list_webhook_deliveries` | List delivery attempts for a webhook                         |

#### `create_webhook` Parameters

| Parameter | Type     | Required | Description                                                                                                                      |
| --------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `url`     | string   | Yes      | HTTPS webhook URL                                                                                                                |
| `events`  | string[] | Yes      | Events to subscribe to: `launch.completed`, `launch.failed`, `launch.partial`, `media.ready`, `persona.analyzed`, `post.deleted` |

#### `update_webhook` Parameters

| Parameter | Type          | Required | Description                   |
| --------- | ------------- | -------- | ----------------------------- |
| `id`      | string (UUID) | Yes      | Webhook ID                    |
| `url`     | string        | No       | New HTTPS webhook URL         |
| `events`  | string[]      | No       | New events to subscribe to    |
| `active`  | boolean       | No       | Enable or disable the webhook |

### Dropspace

| Tool                   | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `get_dropspace_status` | Check which platforms have a connected dropspace account |

### Usage

| Tool        | Description                                             |
| ----------- | ------------------------------------------------------- |
| `get_usage` | Get your current plan, usage limits, and billing period |

## API Key & Scopes

Generate an API key at [dropspace.dev/settings](https://dropspace.dev/settings) under the API section.

API keys support scoped permissions:

| Scope      | Access                                                                 |
| ---------- | ---------------------------------------------------------------------- |
| `read`     | List and read launches, personas, connections, dropspace status        |
| `write`    | Create and update launches, personas                                   |
| `delete`   | Delete launches, personas                                              |
| `publish`  | Publish and retry launches                                             |
| `generate` | Generate AI content, retry content generation                          |
| `admin`    | Manage API keys and webhooks                                           |

### Recommended Scopes by Use Case

| Use Case         | Recommended Scopes                                        |
| ---------------- | --------------------------------------------------------- |
| AI agents / MCP  | `read`, `write`, `generate`                               |
| CI/CD publishing | `read`, `publish`                                         |
| Monitoring       | `read`                                                    |
| Full management  | `read`, `write`, `delete`, `publish`, `generate`, `admin` |

## Webhook Events

| Event              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `launch.completed` | All platforms finished posting successfully                  |
| `launch.failed`    | Launch posting failed on all platforms                       |
| `launch.partial`   | Launch posting succeeded on some platforms, failed on others |
| `media.ready`      | Media generation job completed                               |
| `persona.analyzed` | Persona AI analysis completed                                |
| `post.deleted`     | A published post was deleted from its platform               |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run
DROPSPACE_API_KEY=ds_live_... npm start
```