MCP

🚀 img-src MCP Server

The Model Context Protocol (MCP) server for the img-src.io image hosting API. This server allows AI assistants like Claude to interact with your img-src.io account, enabling direct operations such as uploading, searching, listing, and managing images through natural language.

🚀 Quick Start

This MCP server facilitates seamless interaction between AI assistants and your img-src.io account. With it, you can manage your images using natural language.

✨ Features

• Natural Language Interaction: Empowers AI assistants to interact with your img-src.io account using natural language.
• Comprehensive Image Management: Supports operations like uploading, searching, listing, and managing images.

📦 Installation

You can install the server globally using pnpm:

pnpm add -g @img-src/mcp-server

Or run it directly with pnpm dlx:

pnpm dlx @img-src/mcp-server

💻 Usage Examples

Usage with Claude Desktop

Add the following configuration to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

Usage with Claude Code

Add the configuration to your project's .mcp.json (project - scoped) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

Or add it via the CLI:

claude mcp add img-src -- npx @img-src/mcp-server

Then set the API key in your environment or .env file:

export IMG_SRC_API_KEY=imgsrc_your_api_key_here

Usage with Cursor

1. Open Cursor Settings (Cmd+, on macOS / Ctrl+, on Windows/Linux).
2. Navigate to Features > MCP Servers.
3. Click "Add new MCP server".
4. Enter the following configuration:
   • Name: img-src
   • Type: command
   • Command: npx @img-src/mcp-server
5. Add the environment variable IMG_SRC_API_KEY with your API key.

Alternatively, create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

Usage with VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "img-src": {
      "type": "stdio",
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

Or add via CLI:

code --add-mcp '{"name":"img-src","command":"npx","args":["@img-src/mcp-server"],"env":{"IMG_SRC_API_KEY":"imgsrc_your_api_key_here"}}'

⚠️ Important Note

VS Code uses "servers" (not "mcpServers") and requires "type": "stdio".

Usage with Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

Usage with Cline

Open the Cline extension in VS Code, click the MCP Servers icon > Configure MCP Servers, then add:

{
  "mcpServers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

Usage with Zed

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

⚠️ Important Note

Zed uses "context_servers" as the key, embedded within the main settings.json.

Usage with JetBrains IDEs

In IntelliJ IDEA, WebStorm, PyCharm, or other JetBrains IDEs:

1. Go to Settings > Tools > AI Assistant > Model Context Protocol (MCP).
2. Click + (Add) and paste:

{
  "mcpServers": {
    "img-src": {
      "command": "npx",
      "args": ["@img-src/mcp-server"],
      "env": {
        "IMG_SRC_API_KEY": "imgsrc_your_api_key_here"
      }
    }
  }
}

📚 Documentation

Available Tools

upload_image

Upload an image from a local file, URL, or base64 data to your img-src.io account.

Upload ~/Photos/sunset.jpg to img-src as photos/vacation/sunset.jpg

Parameters:

• file_path (optional): Local file path to upload (recommended for large files).
• url (optional): URL of the image to upload.
• data (optional): Base64 - encoded image data.
• mimeType (optional): MIME type of the image (required when using data).
• target_path (optional): Target path for organizing the image.

Note: One of file_path, url, or data must be provided.

list_images

List images in your account, optionally within a specific folder.

List my img-src images in the photos/vacation folder

Parameters:

• folder (optional): Folder path to list.
• limit (optional): Max items to return (default: 50).
• offset (optional): Items to skip for pagination.

search_images

Search for images by filename or path.

Search for img-src images containing "beach"

Parameters:

• query (required): Search query.
• limit (optional): Max results (default: 20).
• offset (optional): Results to skip.

get_image

Get detailed metadata for a specific image.

Get details for my img-src image at photos/vacation/sunset.jpg

Parameters:

• id (required): Image ID (UUID) or filepath.

delete_image

Permanently delete an image.

Delete my img-src image at photos/old/unused.jpg

Parameters:

• id (required): Image ID (UUID) or filepath to delete.

get_usage

View your current usage statistics.

Show my img-src usage stats

get_settings

Get your account settings and configuration.

What are my img-src account settings?

get_cdn_url

Generate a CDN URL with optional image transformations.

Generate an img-src CDN URL for john/photos/beach.jpg resized to 800x600

Parameters:

• username (required): Image owner's username.
• filepath (required): Image path.
• width (optional): Resize width.
• height (optional): Resize height.
• fit (optional): cover, contain, fill, scale - down.
• quality (optional): 1 - 100 (default: 80).
• format (optional): webp, avif, jpeg, png, jxl.

Resources

The MCP server exposes your images as resources that Claude can access directly:

• URI format: imgsrc://images/{imageId}
• Content: JSON metadata including dimensions, formats, and CDN URLs.

Claude can list and read these resources to understand what images you have and their properties.

Prompts

Pre - built prompts for common workflows:

upload-and-share

Upload an image and get shareable CDN URLs.

• Arguments: imageUrl (required), width (optional).

check-usage

Check account usage and storage status.

• No arguments required.

find-images

Search for images by keyword.

• Arguments: query (required).

Example Conversations

Upload and share an image

User: Upload ~/Photos/sunset.jpg to img-src and give me a resized URL

Claude: I'll upload that image and generate a CDN URL for you.

[Uses upload_image tool]

Image uploaded successfully! Here's a resized CDN URL: https://img-src.io/i/yourname/sunset.webp?w=1200&q=85

Search and organize

User: Find all my beach photos

Claude: [Uses search_images with query "beach"]

Found 5 beach photos:

1. photos/vacation/beach-sunset.jpg
2. photos/summer/beach-party.png ...

Check usage

User: How much storage am I using?

Claude: [Uses get_usage tool]

Your img-src.io usage:

• Storage: 245 MB / 500 MB (49%)
• Uploads: 67 / 100 this month
• Bandwidth: 1.2 GB / 1 GB (120% - consider upgrading!)

🔧 Technical Details

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run locally
IMG_SRC_API_KEY=imgsrc_xxx pnpm start

# Type check
pnpm type-check

# Run tests
pnpm test

📄 License

MIT