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:

$3

- 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)

$3

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

$3

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

$3

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

$3

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

$3

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

Installation

``bash
npm install -g sirv-ai-mcp-server
`

Or use directly with npx:

`bash
npx sirv-ai-mcp-server
`

Configuration

$3

`bash


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

$3

Used for local integrations with Claude Desktop and Claude Code.

`bash
npm start


or


npm run dev
`

$3

Used for remote/hosted deployments accessible via HTTPS.

`bash
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

$3

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

$3

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

$3

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

$3

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

$3

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):

`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:

`json
{
"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):

$3

`bash


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
`

$3

nginx configuration example:
`nginx
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

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

Development

`bash


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

$3

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

$3

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

$3

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

$3

`
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

$3

"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

$3

"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

$3

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)

$3

- Report issues: https://github.com/nicholasgriffintn/sirv-ai-mcp-server/issues
- Documentation: https://www.sirv.studio/docs
- Contact support: support@sirv.studio

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

$3

- 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.