@offlinecreator/mcp

@offlinecreator/mcp

MCP server + thin CLI for OfflineCreator Studio.

Gives Cursor, Claude Desktop, Claude Code, Hermes, Windsurf, and other MCP clients tools to list models, check credits, generate images/video, and wait for results.

Current release: @offlinecreator/mcp@0.1.1

Recommended remote MCP: https://mcp.offlinecreatorstudio.com/mcp (Streamable HTTP + OAuth 2.1)

API-key fallback: local stdio or https://offlinecreatorstudio.com/mcp

Setup

Add the recommended URL to your MCP client, then complete Studio browser sign-in and consent. No API key is stored in the client configuration.

For local stdio or legacy remote fallback, create a scoped key in Settings and copy the secret once (oc_live_… or oc_test_…).

Environment

Variable	Required	Description
OFFLINECREATOR_API_KEY	Yes	Personal API key from Settings
OFFLINECREATOR_API_BASE	No	API origin. Default https://offlinecreatorstudio.com. Localhost allowed; other hosts need OFFLINECREATOR_ALLOW_INSECURE_API_BASE=true.
OFFLINECREATOR_UPLOAD_ROOT	No	Directory that upload_input file paths must stay inside (default: process cwd).
OFFLINECREATOR_ALLOW_INSECURE_API_BASE	No	Set true only for private/non-prod API hosts.

Security notes

• API keys stay in env / MCP client config — tools never echo them.
• upload_input cannot read arbitrary disk paths: paths must stay under the upload root, use image extensions, pass size limits, and match image magic bytes.
• The client only calls /api/v1/* on a trusted API origin (HTTPS except localhost).
• Generations still use Studio moderation, credit reserve/refund, and ownership checks.

Install by client

Cursor

Recommended remote OAuth:

{
  "mcpServers": {
    "offlinecreator": {
      "url": "https://mcp.offlinecreatorstudio.com/mcp"
    }
  }
}

API-key stdio fallback:

{
  "mcpServers": {
    "offlinecreator": {
      "command": "npx",
      "args": ["-y", "@offlinecreator/mcp"],
      "env": {
        "OFFLINECREATOR_API_KEY": "oc_live_…"
      }
    }
  }
}

Never put the key in the URL or use ?api_key=.

Local monorepo development:

{
  "mcpServers": {
    "offlinecreator": {
      "command": "node",
      "args": ["C:/path/to/mcp_tool/packages/mcp/dist/index.js"],
      "env": {
        "OFFLINECREATOR_API_KEY": "oc_test_…",
        "OFFLINECREATOR_API_BASE": "http://localhost:3000"
      }
    }
  }
}

Claude Desktop

Add https://mcp.offlinecreatorstudio.com/mcp in Settings → Connectors → Add custom connector. Use the stdio JSON above in %APPDATA%\Claude\claude_desktop_config.json as the API-key fallback.

Claude Code

Remote OAuth:

claude mcp add offlinecreator --transport http https://mcp.offlinecreatorstudio.com/mcp

Local stdio:

claude mcp add offlinecreator --env OFFLINECREATOR_API_KEY=oc_live_… -- npx -y @offlinecreator/mcp

Hermes

Add to ~/.hermes/config.yaml, then run /reload-mcp:

mcp_servers:
  offlinecreator:
    url: "https://mcp.offlinecreatorstudio.com/mcp"

Windsurf

Add to %USERPROFILE%\.codeium\windsurf\mcp_config.json:

{
  "mcpServers": {
    "offlinecreator": {
      "serverUrl": "https://mcp.offlinecreatorstudio.com/mcp"
    }
  }
}

VS Code / Copilot

VS Code uses servers rather than mcpServers. Add to .vscode/mcp.json or the MCP user configuration:

{
  "servers": {
    "offlinecreator": {
      "type": "http",
      "url": "https://mcp.offlinecreatorstudio.com/mcp"
    }
  }
}

Legacy remote API-key fallback

Clients that support fixed headers can still use:

{
  "mcpServers": {
    "offlinecreator": {
      "url": "https://offlinecreatorstudio.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:OFFLINECREATOR_API_KEY}"
      }
    }
  }
}

Never put a key in the URL or use ?api_key=.

Tools

Tool	Purpose
list_models	Launch catalog + credit costs
get_credits	Current balance
generate	Start generation (wait: true to poll)
upload_input	Attach image for image-to-video, then submit
get_generation	Current status
wait_generation	Poll until done
download_output	Short-lived signed URL for a completed output
cancel_generation	Cancel reserved job + refund
list_generations	Recent jobs

Tools are filtered by key scope (models, read, generate). Top-up discovery and Checkout creation are CLI/API features, not MCP tools. They always return a URL for a human browser action; agents never charge a payment method directly.

CLI sugar

npx @offlinecreator/mcp models
npx @offlinecreator/mcp balance
npx @offlinecreator/mcp topups
npx @offlinecreator/mcp topup --id topup-1000
npx @offlinecreator/mcp generate --model flux-schnell --prompt "A clean product still" --wait

Development

npm install
npm run mcp:build
OFFLINECREATOR_API_KEY=oc_test_… OFFLINECREATOR_API_BASE=http://localhost:3000 npm run mcp:start

Privacy note

Studio generations run on disclosed cloud providers (not on-device). LocalForge remains the offline product.