qiniu-mcp/SETUP.md

A Model Context Protocol server for Qiniu Cloud Storage services with optimized local file upload support

# Qiniu MCP Setup Guide

This guide will help you set up the Qiniu MCP server for use with Cursor, Claude Desktop, and Raycast.

## Prerequisites

- Node.js 18+ installed
- Qiniu Cloud Storage account with API credentials
- Access to a server for deploying the remote MCP server (optional, uses mcp.qiaomu.ai by default)

## Step 1: Installation

### Global Installation (Recommended)

```bash
npm install -g qiniu-mcp
```

### Local Installation

```bash
npm install qiniu-mcp
```

## Step 2: Get Qiniu Credentials

1. Log in to your [Qiniu Cloud Console](https://portal.qiniu.com/)
2. Go to "密钥管理" (Key Management)
3. Create or copy your Access Key and Secret Key
4. Note your bucket names and regions

## Step 3: Configuration

You need to configure your Qiniu credentials. Choose one of the following methods:

### Method A: Environment Variables

Add these to your shell profile (`.bashrc`, `.zshrc`, etc.):

```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 B: 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"
}
```

## Step 4: Application Setup

### For 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": []
    }
  }
}
```

### For Claude Desktop

1. Open Claude Desktop settings
2. Navigate to the MCP servers configuration
3. Add:

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

### For Raycast

1. Install the MCP extension in Raycast
2. Configure it to use the `qiniu-mcp` command
3. Set up the server configuration as needed

## Step 5: Testing

Test your setup by asking your AI assistant:

```
Upload a file to my Qiniu bucket
```

```
List files in my bucket
```

```
Generate a download URL for a file
```

## Advanced Configuration

### Custom Server Endpoint

If you're running your own MCP server:

```bash
export QINIU_MCP_ENDPOINT="https://your-server.com/qiniu/api"
```

Or in your config file:

```json
{
  "accessKey": "your_access_key",
  "secretKey": "your_secret_key",
  "serverEndpoint": "https://your-server.com/qiniu/api"
}
```

### Multiple Configurations

You can create project-specific configurations by placing `.qiniu-mcp.json` in your project directory.

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

### Qiniu-Specific Issues

1. **Bucket not found**: Verify the bucket name and region are correct
2. **Permission denied**: Check your Qiniu account permissions
3. **Upload failed**: Verify file paths and bucket write permissions

### Debug Mode

Run with debug output:

```bash
DEBUG=* qiniu-mcp
```

### Getting Help

1. Check the [README](README.md) for basic usage
2. Review the [Changelog](CHANGELOG.md) for recent updates
3. Open an issue on GitHub if you encounter problems

## Server Deployment (Optional)

If you want to deploy your own MCP server:

1. Clone the repository
2. Configure the server environment
3. Run the deployment script:

```bash
./deploy.sh
```

This will deploy the server to your configured host.

## Security Notes

- Keep your API credentials secure and never commit them to version control
- Use environment variables in production environments
- The client uses HTTPS for all communications with the server
- API keys are sent securely to the remote server and not stored in the npm package
- Consider using IAM policies to limit Qiniu API permissions