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

Method 1: Project .env File (Recommended)

1. Install once:

npm i -g mcp-cos-upload

2. Create a .env file in your project root:

# Copy the template
cp .env.example .env
# Then fill in your values

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

3. Add MCP configuration (Cursor Settings → MCP):

{
  "mcpServers": {
    "mcp-cos-upload": {
      "command": "mcp-cos-upload"
    }
  }
}

Why this is recommended: MCP startup stays short and predictable. The server only executes the installed binary and does not run npm during startup.

Why not npx? npm's npx -y outputs package installation info to stdout, which conflicts with MCP's stdio protocol.

Note: The .env file contains secrets — never commit it. Use .env.example as a reference template.

The server only reads one file:

1. <project-root>/.env

It does not read:

1. MCP env configuration
2. Home directory .env
3. Parent directory .env
4. COS_ENV_PATH

Project root is inferred from the current working directory by walking upward and finding common project markers such as .git, package.json, pnpm-workspace.yaml, .cursor, or .mcp.json. After the root is determined, only that single .env file is read.

Method 2: Auto-Install On First Run (Optional)

Use this only if you explicitly want convenience over startup stability:

{
  "mcpServers": {
    "mcp-cos-upload": {
      "command": "sh",
      "args": ["-c", "command -v mcp-cos-upload >/dev/null 2>&1 || npm i -g mcp-cos-upload >/dev/null 2>&1; exec mcp-cos-upload"]
    }
  }
}

This mode installs automatically only when the command is missing. It does not auto-update an already installed version.

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

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

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
├── .env.example    # Environment variables template
├── 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) |

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

Compression is enabled by default. Use compress: false to upload original files.

Troubleshooting

Unexpected token / JSON parse error on startup

This happens when using npx -y mcp-cos-upload directly — npm outputs package installation info to stdout, breaking MCP's stdio protocol. Use the recommended direct command config in Quick Start instead.

Missing COS_SECRET_ID or COS_SECRET_KEY

The server only reads process.cwd()/.env. If that file does not exist, or if it is missing COS_SECRET_ID / COS_SECRET_KEY, tool calls will return a clear error telling you which path it tried and what the current working directory was.

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