mcp-cos-upload

MCP server for uploading files to Tencent Cloud COS. Supports uploading from URL (e.g., Figma export), local file path, or text content.

Features

• 🚀 Multiple upload sources - URL, local file, or text content
• 🗜️ Smart image compression - PNG, JPEG, WebP, GIF, SVG auto-optimization
• 📁 Auto-organized storage - Files stored by date folders with random suffix
• 🔗 CDN support - Returns CDN URL for fast access

Publishing to npm

# 1. Update version in package.json
npm version patch  # or minor/major

# 2. Login to npm (first time only)
npm login

# 3. Publish
npm publish

# 4. Verify
npm info mcp-cos-upload

After publishing, team members can use it immediately (see Quick Start below).

For Team Members (Users)

Quick Start

Add the MCP configuration (Cursor Settings → MCP). Everyone can use the exact same config — no manual install and no per-machine paths. npx -y automatically downloads and runs the server, and all configuration is read from the env block:

{
  "mcpServers": {
    "mcp-cos-upload": {
      "command": "sh",
      "args": ["-c", "exec \"$SHELL\" -ilc 'exec npx -y mcp-cos-upload'"],
      "env": {
        "COS_SECRET_ID": "your_secret_id",
        "COS_SECRET_KEY": "your_secret_key",
        "COS_DEFAULT_BUCKET": "your_bucket_name",
        "COS_DEFAULT_REGION": "ap-guangzhou",
        "COS_KEY_PREFIX": "figma-assets",
        "COS_CDN_DOMAIN": "cdn.example.com"
      }
    }
  }
}

That's it. The server reads all configuration only from the MCP env block above. It does not read any local .env file, home directory config, or environment file on disk.

Why the sh -c "exec \"$SHELL\" -ilc ..." wrapper instead of just "command": "npx"? When Cursor is launched from the Dock/Finder (macOS), it does not inherit your terminal's PATH. If Node is installed via a version manager (nvm, fnm, Volta) or Homebrew on Apple Silicon (/opt/homebrew/bin), a bare "command": "npx" cannot be found and the server gets stuck on "Loading tools" forever. The wrapper starts your own login shell ($SHELL -ilc), which loads your ~/.zshrc / ~/.bashrc (where nvm/fnm/brew live), so npx resolves correctly for every user with one shared config.

Windows users: use "command": "npx" with "args": ["-y", "mcp-cos-upload"] instead (the shell wrapper above is for macOS/Linux).

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | COS_SECRET_ID | ✅ | Tencent Cloud SecretId | | COS_SECRET_KEY | ✅ | Tencent Cloud SecretKey | | COS_DEFAULT_BUCKET | ✅ | Default COS bucket name | | COS_DEFAULT_REGION | ✅ | Default COS region (e.g., ap-guangzhou, ap-beijing) | | COS_KEY_PREFIX | ❌ | Key prefix for uploaded files (default: figma-assets) | | COS_CDN_DOMAIN | ❌ | Custom CDN domain (e.g., cdn.example.com) | | COS_INTERNAL | ❌ | Set to open to upload via the Tencent Cloud internal endpoint {Bucket}.cos-internal.{Region}.tencentcos.cn (for buckets that only allow intranet access). |

Usage Examples

Just tell AI what you want to upload:

上传这张图片：/Users/me/Downloads/screenshot.png

Upload this image to COS: https://example.com/image.png

The AI will automatically:

1. Call the cos_upload tool
2. Compress the image (if applicable)
3. Upload to COS with date-organized path
4. Return the CDN URL

Upload Path Structure

Files are automatically organized:

{COS_KEY_PREFIX}/{YYYY-MM-DD}/{filename}_{random}.{ext}

Example:
figma-assets/2025-12-22/screenshot_a3b8k2.png

For Developers

Development Setup

# Clone the repository
git clone https://github.com/user/mcp-cos-upload.git
cd mcp-cos-upload

# Install dependencies
npm install

Local Development

Method 1: Direct Node Execution

# Set environment variables
export COS_SECRET_ID="your_secret_id"
export COS_SECRET_KEY="your_secret_key"
export COS_DEFAULT_BUCKET="your_bucket"
export COS_DEFAULT_REGION="ap-guangzhou"

# Run the MCP server
node src/index.js

The server reads configuration only from environment variables (process.env), so any method that sets them (shell export, MCP env block, etc.) works.

Method 2: Configure in Cursor for Testing

Point to your local development path:

{
  "mcpServers": {
    "mcp-cos-upload": {
      "command": "node",
      "args": ["/path/to/mcp-cos-upload/src/index.js"],
      "env": {
        "COS_SECRET_ID": "your_secret_id",
        "COS_SECRET_KEY": "your_secret_key",
        "COS_DEFAULT_BUCKET": "your_bucket",
        "COS_DEFAULT_REGION": "ap-guangzhou"
      }
    }
  }
}

After modifying code, restart Cursor or disable/enable the MCP to reload.

Project Structure

mcp-cos-upload/
├── src/
│   ├── index.js    # MCP server entry, tool definitions
│   └── cos.js      # COS client configuration
├── package.json
├── CHANGELOG.md
└── README.md

Tool Reference

cos_upload

Upload a file to Tencent Cloud COS.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | ❌ | URL to download and upload | | filepath | string | ❌ | Local file path to upload | | content | string | ❌ | Text content to upload | | bucket | string | ❌ | COS bucket name (uses env default) | | region | string | ❌ | COS region (uses env default) | | key | string | ❌ | Object key (auto-generated if not provided) | | folder | string | ❌ | Folder prefix (default: figma-assets, use server config) | | filename | string | ❌ | Custom filename | | ext | string | ❌ | File extension (e.g., png, jpg, svg) | | compress | boolean | ❌ | Enable image compression (default: true) | | quality | number | ❌ | Compression quality 1-100 (default: 80) | | maxWidth | number | ❌ | Max width (px) when compressing; downscale-only, default 1280 (bitmaps) | | maxHeight | number | ❌ | Max height (px) when compressing; downscale-only, default 1280 (bitmaps) |

Note: url, filepath, and content are mutually exclusive - provide only one.

Response:

{
  "bucket": "your-bucket",
  "region": "ap-guangzhou",
  "key": "figma-assets/2025-12-22/image_a3b8k2.png",
  "cdnUrl": "https://cdn.example.com/figma-assets/2025-12-22/image_a3b8k2.png"
}

Image Compression

Supports automatic compression for uploaded images:

| Format | Compression Method | |--------|-------------------| | PNG | Palette mode + color quantization (TinyPNG-like) | | JPEG | mozjpeg encoder with trellis quantization | | WebP | Smart subsampling | | GIF | Optimization | | SVG | SVGO (removes redundant code) |

Before quantizing/encoding, bitmaps (PNG/JPEG/WebP/GIF) are auto-downscaled to fit within a maxWidth × maxHeight bounding box (default 1280, downscale-only, aspect ratio and alpha transparency preserved). This is the biggest size saver for oversized assets — quantization alone keeps the original pixel dimensions. Example: a 1728×2432 PNG goes 1220KB → 297KB (quantize only) → 98KB (downscale to 1280 box + quantize).

Compression is enabled by default. Use compress: false to upload original files, or set maxWidth/maxHeight to control the downscale cap.

Troubleshooting

Missing COS_SECRET_ID or COS_SECRET_KEY

The server reads all configuration from the MCP env block only. If COS_SECRET_ID / COS_SECRET_KEY are missing, tool calls will return a clear error asking you to set them in the MCP env configuration.

MCP not working after code changes

Restart Cursor or toggle the MCP off/on in settings to reload the server.

Permission denied

Ensure your COS_SECRET_ID and COS_SECRET_KEY have write access to the bucket.

Upload failed with network error

Check if your network can access Tencent Cloud COS endpoints.

License

MIT