Qiniu MCP (Model Context Protocol)

A Model Context Protocol server for Qiniu Cloud Storage services, enabling AI assistants like Claude, Cursor, and Raycast to interact with Qiniu Cloud Storage.

🌟 Features

• 🔒 Secure Remote Architecture: API keys stay on your server, not in the npm package
• 📦 Easy Installation: Install via npm and configure with your credentials
• 🚀 Multiple AI Platforms: Works with Cursor, Claude Desktop, and Raycast
• ☁️ Full Qiniu Integration: Upload, download, list, delete, copy, and move files
• 🔧 Flexible Configuration: Environment variables or config files
• ⚡ High Performance: Built with TypeScript and modern Node.js

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Client     │    │   npm package   │    │  Remote Server  │
│ (Cursor/Claude) │◄──►│  (qiniu-mcp)    │◄──►│ (mcp.qiaomu.ai) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  User Config    │    │  Qiniu Cloud    │
                       │  (API Keys)     │    │     APIs        │
                       └─────────────────┘    └─────────────────┘

📦 Installation

Global Installation (Recommended)

npm install -g @vista8/qiniu-mcp

Local Installation

npm install @vista8/qiniu-mcp

⚙️ Configuration

Method 1: Environment Variables

export QINIU_ACCESS_KEY="your_access_key"
export QINIU_SECRET_KEY="your_secret_key"
export QINIU_BUCKET="your_default_bucket"      # Optional
export QINIU_REGION="z0"                       # Optional (z0=华东, z1=华北, z2=华南)
export QINIU_DOMAIN="your_custom_domain.com"   # Optional

Method 2: Configuration File

Create ~/.qiniu-mcp.json:

{
  "accessKey": "your_access_key",
  "secretKey": "your_secret_key",
  "bucket": "your_default_bucket",
  "region": "z0",
  "domain": "your_custom_domain.com"
}

🔧 Usage with AI Clients

Cursor

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP" or go to Extensions > MCP
3. Add the following configuration:

{
  "mcp.servers": {
    "qiniu": {
      "command": "qiniu-mcp",
      "args": []
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "qiniu": {
      "command": "qiniu-mcp",
      "args": []
    }
  }
}

Raycast

1. Install the MCP extension in Raycast
2. Configure it to use the qiniu-mcp command

🛠️ Available Tools

qiniu_upload_file

Upload a file to Qiniu Cloud Storage (server-side file path).

Parameters:

• filePath (required): Server-side file path to upload
• bucket (optional): Target bucket name (uses default if not provided)
• key (optional): Object key (filename) in the bucket
• expires (optional): Upload token expiration time in seconds

qiniu_upload_local_file ⭐ NEW

Upload a local file to Qiniu Cloud Storage (optimized for client-side files).

Parameters:

• filePath (required): Local file path or file:// URL to upload
• bucket (optional): Target bucket name (uses default if not provided)
• key (optional): Object key (filename) in the bucket
• expires (optional): Upload token expiration time in seconds

Features:

• ✅ Supports local file paths and file:// URLs
• ✅ Automatic content type detection
• ✅ Optimized for client-side file uploads
• ✅ No manual base64 conversion required

qiniu_upload_content

Upload text content directly to Qiniu Cloud Storage.

Parameters:

• content (required): Text content to upload
• bucket (optional): Target bucket name (uses default if not provided)
• key (required): Object key (filename) in the bucket
• contentType (optional): MIME type (default: 'text/plain')
• expires (optional): Upload token expiration time in seconds

qiniu_upload_base64

Upload base64 encoded binary content to Qiniu Cloud Storage.

Parameters:

• base64Content (required): Base64 encoded content (without data URI prefix)
• bucket (optional): Target bucket name (uses default if not provided)
• key (required): Object key (filename) in the bucket
• contentType (optional): MIME type (default: 'application/octet-stream')
• expires (optional): Upload token expiration time in seconds

qiniu_upload_from_url ⭐ NEW

Upload a file from URL directly to Qiniu Cloud Storage (faster than base64).

Parameters:

• url (required): URL of the file to upload
• bucket (optional): Target bucket name (uses default if not provided)
• key (optional): Object key (filename) in the bucket (auto-generated if not provided)
• expires (optional): Upload token expiration time in seconds

Features:

• ✅ Direct upload from remote URLs
• ✅ No base64 conversion overhead
• ✅ Automatic content type detection
• ✅ Faster than traditional base64 upload

qiniu_list_files

List files in a Qiniu Cloud Storage bucket.

Parameters:

• bucket (required): Bucket name to list files from
• prefix (optional): File prefix to filter results
• limit (optional): Maximum number of files to return (default: 100, max: 1000)
• marker (optional): Marker for pagination

qiniu_delete_file

Delete a file from Qiniu Cloud Storage.

Parameters:

• bucket (required): Bucket name
• key (required): Object key (filename) to delete

qiniu_get_file_info

Get detailed information about a file.

Parameters:

• bucket (required): Bucket name
• key (required): Object key (filename)

qiniu_generate_download_url

Generate a download URL for a file.

Parameters:

• bucket (required): Bucket name
• key (required): Object key (filename)
• domain (optional): Custom domain for the download URL
• expires (optional): URL expiration time in seconds (default: 3600)
• private (optional): Whether the file is in a private bucket (default: false)

qiniu_copy_file

Copy a file within Qiniu Cloud Storage.

Parameters:

• sourceBucket (required): Source bucket name
• sourceKey (required): Source object key
• targetBucket (required): Target bucket name
• targetKey (required): Target object key

qiniu_move_file

Move/rename a file within Qiniu Cloud Storage.

Parameters:

• sourceBucket (required): Source bucket name
• sourceKey (required): Source object key
• targetBucket (required): Target bucket name
• targetKey (required): Target object key

💡 Example Usage

Once configured, you can ask your AI assistant:

Local File Upload (Recommended)

Upload the local file ~/Documents/report.pdf to my qiniu bucket

Upload from URL

Upload the image from https://example.com/image.jpg to my qiniu bucket

File Management

List all files in my "images" bucket that start with "2024/"

Delete the file "old-document.pdf" from my documents bucket

Performance Comparison

• Local File Upload: qiniu_upload_local_file - Optimized for client files
• URL Upload: qiniu_upload_from_url - Direct upload, no base64 conversion
• Base64 Upload: qiniu_upload_base64 - For when you already have base64 data
• Server File Upload: qiniu_upload_file - For files on the server

Generate a download URL for the file "report.pdf" in bucket "documents"

Copy the file "old-logo.png" from bucket "assets" to "backup" bucket as "logo-backup.png"

🔍 Troubleshooting

Connection Issues

1. Server unreachable: Check your internet connection and firewall settings
2. Authentication failed: Verify your Qiniu access key and secret key are correct
3. SSL/TLS errors: The client handles self-signed certificates automatically

Configuration Issues

1. Command not found: Ensure the package is installed globally or use the full path
2. Permission denied: Check file permissions on your config file
3. Invalid JSON: Validate your configuration file syntax

Debug Mode

Run with debug output:

DEBUG=* qiniu-mcp

🏗️ Development

Building from Source

git clone https://github.com/vista8/qiniu-mcp.git
cd qiniu-mcp
npm install
npm run build

Running Tests

npm test

Server Development

The remote server code is in the server/ directory:

cd server
npm install
npm run dev

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation