npm package: @subscribe.dev/mcp
Description: Model Context Protocol (MCP) server for Subscribe.dev - manage projects and deployments directly from Claude Code
Author: Volter AI
Latest version: 0.4.14

# @subscribe.dev/mcp

> Model Context Protocol (MCP) server for Subscribe.dev - manage projects and deployments directly from Claude Code

[![npm version](https://img.shields.io/npm/v/@subscribe.dev/mcp.svg)](https://www.npmjs.com/package/@subscribe.dev/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

This MCP server enables Claude Code and other MCP-compatible clients to interact with Subscribe.dev directly. Create projects, deploy applications, and manage your Subscribe.dev infrastructure without leaving your AI assistant.

### What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that allows AI assistants like Claude to securely connect to external tools and data sources. Think of it as "USB-C for AI" - a universal way to extend AI capabilities.

### What can this MCP server do?

- **Project Management**: Create, list, view, and delete Subscribe.dev projects
- **Deployments**: Deploy HTML/web content to your projects instantly
- **File Uploads**: Upload files and get public URLs for use with AI models
- **AI Model Execution**: Run text, image, and video AI models directly from Claude Code
  - **Text AI**: GPT-4o, GPT-5, Claude, Gemini 3 Pro, and more for chat and completions
  - **Image AI**: FLUX, Stable Diffusion for image generation and editing
  - **Video AI**: Sora, SeeDance, Kling Turbo for text-to-video and image-to-video generation
  - **Lipsync**: Sync audio with video for realistic lip movements
- **API Keys**: Retrieve project API keys for further development
- **Seamless Integration**: Works natively with Claude Code and other MCP clients

## Installation

### Quick Start with Claude Code

The easiest way to use this MCP server is with Claude Code's built-in MCP support:

```bash
# Add the MCP server to Claude Code
claude mcp add subscribe-dev

# Or manually add to your Claude Code config
```

### Manual Installation

```bash
# Install globally via npm
npm install -g @subscribe.dev/mcp

# Or use npx (no installation required)
npx @subscribe.dev/mcp
```

## Configuration

### Required: Platform API Key

You need a Subscribe.dev platform API key to use this MCP server:

1. Visit https://dashboard.subscribe.dev/api-keys
2. Click "Create API Key"
3. Give it a name (e.g., "Claude Code MCP")
4. Choose an expiration period
5. Copy the generated key (starts with `sdp_`)

### Setting up the API Key

Set the environment variable `SUBSCRIBE_DEV_API_KEY`:

```bash
# Option 1: Export in your shell
export SUBSCRIBE_DEV_API_KEY=sdp_your_key_here

# Option 2: Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export SUBSCRIBE_DEV_API_KEY=sdp_your_key_here' >> ~/.zshrc

# Option 3: Use .env file (if your MCP client supports it)
# Create a .env file with:
SUBSCRIBE_DEV_API_KEY=sdp_your_key_here
```

### Claude Code Configuration

Add this to your Claude Code MCP configuration file (`~/.claude.json` or via `claude mcp add`):

```json
{
  "mcpServers": {
    "subscribe-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@subscribe.dev/mcp"],
      "env": {
        "SUBSCRIBE_DEV_API_KEY": "sdp_your_key_here"
      }
    }
  }
}
```

**Alternative**: If installed globally:

```json
{
  "mcpServers": {
    "subscribe-dev": {
      "type": "stdio",
      "command": "subscribe-dev-mcp",
      "env": {
        "SUBSCRIBE_DEV_API_KEY": "sdp_your_key_here"
      }
    }
  }
}
```

## Available Tools

### `subscribe_dev_create_project`

Create a new Subscribe.dev project.

**Parameters:**
- `name` (required): Project name (1-100 characters)
- `description` (optional): Project description
- `type` (optional): `"demo"`, `"dev"`, or `"production"` (default: `"dev"`)
- `authCallbackUrl` (optional): Callback URL for user authentication
- `authCallbackEnabled` (optional): Enable auth callback (default: `false`)

**Returns:** Project details including the API key ⚠️ *Save it - shown only once!*

**Example:**
```
Create a new Subscribe.dev project called "My AI App"
```

### `subscribe_dev_list_projects`

List all your Subscribe.dev projects with pagination.

**Parameters:**
- `limit` (optional): Number of projects to return (1-100, default: 10)
- `offset` (optional): Pagination offset (default: 0)

**Returns:** Array of projects and pagination metadata

**Example:**
```
List my Subscribe.dev projects
```

### `subscribe_dev_get_project`

Get detailed information about a specific project.

**Parameters:**
- `projectId` (required): Project ID (UUID format)

**Returns:** Complete project details

**Example:**
```
Get details for project d789e442-5b0b-4837-8a03-95171a05d74f
```

### `subscribe_dev_get_project_api_key`

Retrieve the API key for a project (for making API requests).

**Parameters:**
- `projectId` (required): Project ID (UUID format)

**Returns:** The project's API key

**Example:**
```
Get the API key for project d789e442-5b0b-4837-8a03-95171a05d74f
```

### `subscribe_dev_delete_project`

Delete a project permanently.

**Parameters:**
- `projectId` (required): Project ID to delete (UUID format)

**Returns:** Confirmation message

**Example:**
```
Delete project d789e442-5b0b-4837-8a03-95171a05d74f
```

### `subscribe_dev_deploy_content`

Deploy HTML or file content to a project. Your content goes live instantly!

**Parameters:**
- `projectId` (required): Project ID to deploy to (UUID format)
- `content` (required): HTML/file content to deploy
- `isBase64` (optional): Whether content is base64 encoded (default: `false`)

**Returns:** Deployment ID and live URL

**Example:**
```
Deploy this HTML to project d789e442-5b0b-4837-8a03-95171a05d74f:
<!DOCTYPE html>
<html>
<head><title>Hello World</title></head>
<body><h1>Hello from Claude Code!</h1></body>
</html>
```

### `upload_file`

Upload a file (image, video, audio) and get a public CloudFront URL. Perfect for uploading reference images to use with AI models.

**Parameters:**
- `filePath` (required): Absolute path to the file to upload

**Supported file types:**
- Images: jpg, jpeg, png, webp, gif
- Videos: mp4, webm, mov
- Audio: mp3, wav

**Returns:** Public CloudFront URL

**Example:**
```
Upload the file at /Users/alice/photo.jpg
```

**Use with AI models:**
```
1. Upload a reference image
2. Use the returned URL with run_image_ai or run_video_ai
```

### `run_text_ai`

Execute text AI models (GPT, Claude, Gemini, etc.) and bill usage to your demo project.

**Parameters:**
- `model` (required): Model identifier (e.g., `"openai/gpt-4o"`, `"openai/gpt-5"`, `"google/gemini-3-pro-preview"`, `"anthropic/claude-3.5-sonnet"`)
- `input` (required): Object containing:
  - `prompt` (optional): Text prompt for completion

**Returns:** AI-generated text response with metrics

**Examples:**
```
Generate a haiku about coding using GPT-4o

Generate a haiku about coding using GPT-5

Generate a haiku about coding using Gemini 3 Pro
```

### `run_image_ai`

Generate images using AI models (FLUX, Stable Diffusion, etc.) and bill usage to your demo project.

**Parameters:**
- `model` (required): Model identifier (e.g., `"black-forest-labs/flux-schnell"`, `"google/nano-banana-pro"`)
- `input` (required): Object containing:
  - `prompt` (required): Description of the image to generate
  - `aspect_ratio` (optional): Image aspect ratio (e.g., `"16:9"`, `"1:1"`)
  - `output_format` (optional): Output format (`"jpg"`, `"png"`, `"webp"`)
  - `image_input` (optional): Array of reference image URLs for nano-banana-pro
  - `input_image` (optional): Single reference image URL for flux-kontext-max
  - `remove_background` (optional): Remove background (returns PNG with transparency)

**Returns:** Image URL(s) with metrics

**Example:**
```
Generate an image of a sunset over mountains using flux-schnell
```

### `run_video_ai`

Generate or process videos using AI models (Sora, SeeDance, Kling Turbo, Lipsync, etc.) and bill usage to your demo project.

**Parameters:**
- `model` (required): Model identifier
  - Text-to-video: `"openai/sora-2"`, `"openai/sora-2-pro"`, `"bytedance/seedance-1-lite"`, `"bytedance/seedance-1-pro"`, `"kwaivgi/kling-v2.5-turbo-pro"`
  - Lipsync: `"sync/lipsync-2"`
- `input` (required): Object containing model-specific parameters

**Text-to-Video Models:**
- `prompt` (required): Description of the video to generate
- `image` (optional): Start frame image URL (seedance models)
- `start_image` (optional): First frame image URL (kling models)
- `input_reference` (optional): First frame image URL (sora models)
- `aspect_ratio` (optional): Video aspect ratio
  - seedance: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`, `"21:9"`, `"9:21"` (default: `"16:9"`)
  - sora: `"portrait"` (720x1280), `"landscape"` (1280x720) (default: `"portrait"`)
  - kling: `"16:9"`, `"9:16"`, `"1:1"` (default: `"16:9"`, ignored if start_image provided)
- `seconds` (optional): Duration in seconds (sora: 4/8/12)
- `duration` (optional): Duration in seconds (seedance: 2-12, kling: 5 or 10, default: 5)
- `resolution` (optional): Video resolution (model-specific)
- `negative_prompt` (optional): Things to avoid in the video (kling)
- `camera_fixed` (optional): Lock camera position (seedance)
- `last_frame_image` (optional): End frame for looping videos (seedance)

**Lipsync Model (`sync/lipsync-2`):**
- `video` (required): Input video URL or base64 to apply lip synchronization
- `audio` (required): Audio URL or base64 to synchronize with the video
- `sync_mode` (optional): Synchronization mode
  - `"loop"`: Loop audio to match video length (default)
  - `"bounce"`: Reverse audio playback when looping
  - `"cut_off"`: Cut off audio at video end
  - `"silence"`: Add silence to match lengths
  - `"remap"`: Remap audio timing to match video
- `temperature` (optional): Generation randomness (0.0-1.0, default: 0.5)

**Returns:** Video URL with metrics

**Examples:**
```
Generate a 5-second video of a cat playing with yarn using seedance-1-pro

Generate a 10-second cinematic video of a surfer riding a wave at sunset using kling-v2.5-turbo-pro

Generate a video from this image https://example.com/sunset.jpg showing the scene transitioning from day to night using kling-v2.5-turbo-pro

Sync this audio https://example.com/speech.mp3 with this video https://example.com/person.mp4 using lipsync-2
```

**Pricing:**
- Kling v2.5 Turbo Pro: $0.07 per second of video output
- Lipsync models: $0.0525 per second of video processed

## Usage Examples

### In Claude Code

Once configured, you can use natural language to interact with Subscribe.dev:

```
You: Create a new dev project called "Todo App"

Claude: I'll create a new dev project for you.
[Creates project using subscribe_dev_create_project]
✓ Project created! Here are the details:
- ID: abc123...
- Name: Todo App
- API Key: pub_xyz... (Save this securely!)
- Type: dev

You: Deploy a simple HTML page to that project

Claude: I'll deploy some HTML content to your Todo App project.
[Deploys using subscribe_dev_deploy_content]
✓ Deployment successful!
Your site is live at: https://abc123.apps.subscribe.dev

You: List all my projects

Claude: Here are your Subscribe.dev projects:
[Lists using subscribe_dev_list_projects]
1. Todo App (dev)
2. Portfolio Site (production)
3. Test Project (demo)
...
```

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/volter-ai/remetricate.git
cd remetricate/packages/mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
SUBSCRIBE_DEV_API_KEY=sdp_your_key_here node dist/index.js
```

### Project Structure

```
packages/mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```

## Troubleshooting

### "SUBSCRIBE_DEV_API_KEY environment variable is required"

Make sure you've set the `SUBSCRIBE_DEV_API_KEY` environment variable with your platform API key. Get one from https://dashboard.subscribe.dev/api-keys

### "Invalid API key format"

Platform API keys must start with `sdp_`. Make sure you're using a **platform API key**, not a project API key (which starts with `pub_`).

### "Module not found"

If you installed globally, make sure `subscribe-dev-mcp` is in your PATH. Try using npx instead:

```json
{
  "command": "npx",
  "args": ["-y", "@subscribe.dev/mcp"]
}
```

### MCP server not appearing in Claude Code

1. Check your configuration file syntax
2. Restart Claude Code
3. Run `claude mcp list` to see registered servers
4. Check logs with `claude mcp get subscribe-dev`

## Related Packages

- [@subscribe.dev/sdk](https://www.npmjs.com/package/@subscribe.dev/sdk) - TypeScript SDK for Subscribe.dev
- [@subscribe.dev/react](https://www.npmjs.com/package/@subscribe.dev/react) - React hooks for Subscribe.dev
- [@subscribe.dev/client](https://www.npmjs.com/package/@subscribe.dev/client) - Core client library

## Resources

- [Subscribe.dev Documentation](https://docs.subscribe.dev)
- [Subscribe.dev Dashboard](https://dashboard.subscribe.dev)
- [Model Context Protocol Docs](https://modelcontextprotocol.io)
- [Claude Code Documentation](https://docs.claude.com/claude-code)

## Support

- **Issues**: [GitHub Issues](https://github.com/volter-ai/remetricate/issues)
- **Discussions**: [GitHub Discussions](https://github.com/volter-ai/remetricate/discussions)
- **Email**: support@volter.ai

## License

MIT © Volter AI

---

**Built with** [Model Context Protocol](https://modelcontextprotocol.io) | **Powered by** [Subscribe.dev](https://subscribe.dev)