qiniu-mcp
Version:
A Model Context Protocol server for Qiniu Cloud Storage services with optimized local file upload support
318 lines (236 loc) β’ 9.37 kB
Markdown
# 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)
```bash
npm install -g qiniu-mcp
```
### Local Installation
```bash
npm install qiniu-mcp
```
## βοΈ Configuration
### Method 1: Environment Variables
```bash
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`:
```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:
```json
{
"mcp.servers": {
"qiniu": {
"command": "qiniu-mcp",
"args": []
}
}
}
```
### Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"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:
```bash
DEBUG=* qiniu-mcp
```
## ποΈ Development
### Building from Source
```bash
git clone https://github.com/yourusername/qiniu-mcp.git
cd qiniu-mcp
npm install
npm run build
```
### Running Tests
```bash
npm test
```
### Server Development
The remote server code is in the `server/` directory:
```bash
cd server
npm install
npm run dev
```
## π License
MIT License - see [LICENSE](LICENSE) file for details.
## π€ Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## π Support
- GitHub Issues: [Report bugs or request features](https://github.com/yourusername/qiniu-mcp/issues)
- Documentation: [Full documentation](https://github.com/yourusername/qiniu-mcp#readme)