Sirv AI MCP Server

MCP (Model Context Protocol) server for Sirv AI Studio - AI-powered image and video processing.

Features

This MCP server exposes the following AI tools:

Image Processing

• sirv_remove_background - Remove backgrounds from images using BiRefNet or Bria
• sirv_upscale - Upscale images 2-4x using ESRGAN, Clarity, or Topaz
• sirv_background_replace - Replace image backgrounds with AI-generated scenes
• sirv_object_removal - Remove objects from images using inpainting
• sirv_depth_map - Generate depth maps from images (FREE)

Image Generation

• sirv_generate - Generate images from text prompts
• sirv_image_to_image - Transform images based on text prompts

Product & E-commerce

• sirv_product_lifestyle - Create lifestyle product shots
• sirv_virtual_try_on - Virtual clothing try-on

3D & Video

• sirv_image_to_3d - Convert images to 3D models
• sirv_video_generation - Generate videos from text/images

Batch Operations

• sirv_batch_remove_background - Process multiple images
• sirv_batch_upscale - Upscale multiple images

Utility

• sirv_alt_text - Generate alt text descriptions
• sirv_get_usage - Check credit usage statistics

Installation

npm install -g sirv-ai-mcp-server

Or use directly with npx:

npx sirv-ai-mcp-server

Configuration

Environment Variables

# Required: Sirv AI Studio URL
SIRV_AI_BASE_URL="https://www.sirv.studio"

# Optional: API key for authentication (if not using OAuth)
SIRV_AI_API_KEY="your-api-key"

# Transport mode: "stdio" (default) or "http"
MCP_TRANSPORT="stdio"

# HTTP server settings (when using http transport)
MCP_HTTP_PORT=3001
MCP_HTTP_HOST=0.0.0.0
MCP_BASE_URL="https://your-mcp-server.com"

# HTTPS (optional - can also use reverse proxy)
MCP_SSL_KEY_PATH="/path/to/key.pem"
MCP_SSL_CERT_PATH="/path/to/cert.pem"

# Security: IP allowlisting
MCP_ENABLE_IP_ALLOWLIST="true"
MCP_ALLOWED_IPS="1.2.3.4,5.6.7.8/24"

# CORS: Allowed origins (comma-separated)
MCP_CORS_ORIGINS="https://claude.ai,https://your-app.com"

Transport Modes

Stdio Transport (Default)

Used for local integrations with Claude Desktop and Claude Code.

npm start
# or
npm run dev

HTTP Transport

Used for remote/hosted deployments accessible via HTTPS.

npm run start:http
# or
npm run dev:http

When running in HTTP mode, the server exposes:

• /mcp - MCP protocol endpoint
• /health - Health check endpoint
• /.well-known/oauth-authorization-server - OAuth 2.0 metadata
• /.well-known/oauth-protected-resource - Protected resource metadata

Security Features

OAuth 2.0 Support

The server implements OAuth 2.0 with PKCE for secure authentication:

• Authorization code flow with S256 code challenge
• Token refresh support
• Secure token storage in ~/.sirv-ai/tokens.json

Tool Safety Annotations

All tools include proper MCP safety annotations:

• readOnlyHint - Indicates if the tool only reads data
• destructiveHint - Indicates if the tool can delete/destroy data
• idempotentHint - Indicates if repeated calls produce the same result
• openWorldHint - Indicates if the tool accesses external services

CORS Configuration

When running in HTTP mode, CORS is configured for browser-based authentication:

• Default allowed origins: https://claude.ai, https://console.anthropic.com
• Customizable via MCP_CORS_ORIGINS environment variable
• Proper preflight handling with credentials support

IP Allowlisting

Optional IP-based access control:

• Pre-configured Claude.ai/Claude Code IP ranges
• Enable with MCP_ENABLE_IP_ALLOWLIST=true
• Add custom IPs/CIDR ranges via MCP_ALLOWED_IPS

HTTPS Support

For production deployments:

1. Direct HTTPS: Set MCP_SSL_KEY_PATH and MCP_SSL_CERT_PATH
2. Reverse Proxy: Run HTTP behind nginx/Caddy with TLS termination

Usage with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "sirv-ai": {
      "command": "npx",
      "args": ["-y", "sirv-ai-mcp-server"],
      "env": {
        "SIRV_AI_BASE_URL": "https://www.sirv.studio"
      }
    }
  }
}

Usage with Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "sirv-ai": {
      "command": "npx",
      "args": ["-y", "sirv-ai-mcp-server"],
      "env": {
        "SIRV_AI_BASE_URL": "https://www.sirv.studio"
      }
    }
  }
}

Remote Server Deployment

For hosting the MCP server remotely (accessible via claude.ai):

1. Deploy with HTTPS

# Using SSL certificates directly
MCP_TRANSPORT=http \
MCP_HTTP_PORT=443 \
MCP_BASE_URL=https://mcp.your-domain.com \
MCP_SSL_KEY_PATH=/etc/ssl/private/key.pem \
MCP_SSL_CERT_PATH=/etc/ssl/certs/cert.pem \
MCP_ENABLE_IP_ALLOWLIST=true \
SIRV_AI_BASE_URL=https://www.sirv.studio \
npm run start:http

2. Or use a reverse proxy (recommended)

nginx configuration example:

server {
    listen 443 ssl http2;
    server_name mcp.your-domain.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. Configure in claude.ai

Once deployed, users can connect via the MCP settings in claude.ai using your server URL.

Development

# Run in development mode with auto-reload (stdio)
npm run dev

# Run in development mode (http)
npm run dev:http

# Build for production
npm run build

# Run the server (stdio)
npm start

# Run the server (http)
npm run start:http

Example Tool Usage

Remove Background

Remove the background from https://example.com/product.jpg

Generate Image

Generate an image of a modern minimalist living room with natural lighting

Upscale Image

Upscale https://example.com/photo.jpg by 4x using the clarity model

Product Lifestyle

Place this product in a cozy kitchen setting with morning light

Credit Costs

| Tool | Credits | |------|---------| | Background Removal | 1-2 | | Upscale | 2-3 | | Generate | 2 | | Image to Image | 2-4 | | Background Replace | 4 | | Object Removal | 3 | | Alt Text | 1 | | Depth Map | FREE | | Virtual Try-On | 4 | | Image to 3D | 80 | | Video Generation | Variable |

Troubleshooting

Connection Issues

"Server not found" or connection refused

• Verify the server is running: npm start for stdio or npm run start:http for HTTP mode
• Check that SIRV_AI_BASE_URL is set correctly
• For HTTP mode, ensure the port isn't blocked by a firewall

"Authentication failed"

• Delete stored tokens: rm -rf ~/.sirv-ai/tokens.json
• Re-authenticate through the OAuth flow
• Verify your account is active at https://www.sirv.studio

"Invalid API key"

• Check that SIRV_AI_API_KEY is correctly set (if using API key auth)
• Regenerate your API key in your Sirv AI Studio account settings

Tool Errors

"Insufficient credits"

• Check your credit balance using sirv_get_usage tool
• Purchase more credits at https://www.sirv.studio/billing

"Image URL not accessible"

• Ensure the image URL is publicly accessible (not behind authentication)
• Try uploading the image to a public hosting service first

"Processing timeout"

• Large images or complex operations may take longer
• Try with a smaller image or lower resolution setting
• Video generation and 3D conversion can take several minutes

HTTP Transport Issues

CORS errors in browser

• Add your origin to MCP_CORS_ORIGINS environment variable
• Example: MCP_CORS_ORIGINS="https://your-app.com,https://claude.ai"

SSL/TLS certificate errors

• Verify certificate paths are correct in MCP_SSL_KEY_PATH and MCP_SSL_CERT_PATH
• Ensure certificates are not expired
• For development, consider using a reverse proxy with Let's Encrypt

IP blocked

• If using IP allowlisting, add your IP to MCP_ALLOWED_IPS
• Check if your IP has changed (dynamic IP addresses)

Getting Help

• Report issues: https://github.com/nicholasgriffintn/sirv-ai-mcp-server/issues
• Documentation: https://www.sirv.studio/docs
• Contact support: [email protected]

Privacy Policy & Terms of Service

By using Sirv AI MCP Server, you agree to our terms and policies:

• Privacy Policy: https://www.sirv.studio/privacy
• Terms of Service: https://www.sirv.studio/terms

Data Handling

• Images are processed through fal.ai APIs and are subject to their data policies
• Generated outputs are stored temporarily for retrieval
• User authentication tokens are stored locally in ~/.sirv-ai/tokens.json
• No user data is collected by the MCP server itself beyond what's necessary for authentication

License

This project is licensed under the MIT License - see the LICENSE file for details.