OSS

You can run a focused MCP server that uploads files directly to Alibaba Cloud OSS, enabling seamless workflows with other MCP tools and services. This server supports multiple OSS configurations and simple upload interfaces to fit your automation and backup needs.

How to use

Start the OSS MCP server in stdio mode and provide your OSS configuration. You can then interact with it via an MCP client to upload files to the designated OSS bucket. For debugging and development, you can run the server with an inspector to diagnose issues more easily.

oss-mcp --oss-config='{"default":{"region":"oss-cn-shenzhen","accessKeyId":"YOUR_KEY","accessKeySecret":"YOUR_SECRET","bucket":"YOUR_BUCKET","endpoint":"oss-cn-shenzhen.aliyuncs.com"}}'

How to install

Prerequisites: Node.js and a package manager (npm or pnpm) installed on your system.

Install the OSS MCP server globally using npm or pnpm.

# Use npm to install globally
npm install -g oss-mcp

# Or use pnpm to install globally
pnpm add -g oss-mcp

Configuration and usage notes

Configure the OSS connections you want to use. You can define multiple OSS configurations and reference them by name when starting the server. Two common methods are through a .env file or by setting environment variables directly when launching the server.

# Example environment variable configuration for multiple OSS setups
OSS_CONFIG_DEFAULT={"region":"oss-cn-hangzhou","accessKeyId":"your-access-key-id","accessKeySecret":"your-access-key-secret","bucket":"your-bucket-name","endpoint":"oss-cn-hangzhou.aliyuncs.com"}
OSS_CONFIG_TEST={"region":"oss-cn-beijing","accessKeyId":"your-access-key-id-2","accessKeySecret":"your-access-key-secret-2","bucket":"your-bucket-name-2","endpoint":"oss-cn-beijing.aliyuncs.com"}

Starting in stdio mode with a single config

Use the following command to start the server in stdio mode with a default OSS configuration.

oss-mcp --oss-config='{"default":{"region":"oss-cn-shenzhen","accessKeyId":"YOUR_KEY","accessKeySecret":"YOUR_SECRET","bucket":"YOUR_BUCKET","endpoint":"oss-cn-shenzhen.aliyuncs.com"}}'

Starting with Inspector for debugging

If you want to debug with an interactive inspector, include the --inspect flag in the start command.

oss-mcp --oss-config='{ "region": "oss-cn-shenzhen", "accessKeyId": "YOUR_KEY", "accessKeySecret": "YOUR_SECRET", "bucket": "BUCKET_NAME", "endpoint": "oss-cn-shenzhen.aliyuncs.com" }' --inspect

From source code to run flow

If you are building from source, follow the standard flow to install dependencies, build, and then start the server. The final start command will run your MCP server in stdio mode.

Configuration methods

Method 1: Using a .env file. Create a .env file at the project root and define multiple OSS configurations for easy switching.

# .env example
OSS_CONFIG_DEFAULT={"region":"oss-cn-hangzhou","accessKeyId":"your-access-key-id","accessKeySecret":"your-access-key-secret","bucket":"your-bucket-name","endpoint":"oss-cn-hangzhou.aliyuncs.com"}
OSS_CONFIG_TEST={"region":"oss-cn-beijing","accessKeyId":"your-access-key-id-2","accessKeySecret":"your-access-key-secret-2","bucket":"your-bucket-name-2","endpoint":"oss-cn-beijing.aliyuncs.com"}

Security and notes

Keep your access keys secret. Use separate OSS configurations for different environments or accounts, and reference them by name when starting the server.

Available tools

upload_to_oss

Upload a local file to the configured OSS bucket, with optional target directory and file name, using a selected OSS configuration.

list_oss_configs

Return the available OSS configuration names that you can reference when starting the server.