zq940222/OssHub

OssHub - Universal Object Storage MCP Server

OssHub is a Model Context Protocol (MCP) server that provides unified access to multiple cloud object storage services. It allows AI assistants like Claude to interact with unstructured data stored in cloud object storage.

Features

• Multi-Provider Support: Connect to multiple cloud object storage services:

  • Huawei Cloud OBS (华为云对象存储)
  • Alibaba Cloud OSS (阿里云对象存储)
  • AWS S3 / S3-Compatible (MinIO, Backblaze B2, DigitalOcean Spaces, etc.)
  • More providers coming soon (Tencent Cloud COS, etc.)

• Multi-Source Configuration: Connect to multiple storage sources simultaneously with unique identifiers

• Built-in Tools:

  • list_buckets - List all storage buckets
  • list_objects - List objects in a bucket with filtering and pagination
  • get_object - Retrieve object content (text as plain text, binary as base64)
  • get_object_metadata - Get object metadata without downloading content
  • search_objects - Search objects with advanced filters (extension, size, date, pattern)

• Flexible Configuration: TOML configuration file or environment variables

Installation

# Clone the repository
git clone https://github.com/your-org/osshub.git
cd osshub

# Install dependencies
npm install
# or
pnpm install

# Build
npm run build
# or
pnpm build

Quick Start

1. Create Configuration File

Create osshub.toml in your project directory:

[[sources]]
id = "my_obs"
type = "obs"
endpoint = "https://obs.cn-east-2.myhuaweicloud.com"
access_key = "your-access-key"
secret_key = "your-secret-key"
region = "cn-east-2"

2. Run the Server

# STDIO mode (for MCP clients like Claude Desktop)
npm start

# HTTP mode (for web-based MCP clients)
npm start -- --transport=http --port=8080

3. Configure MCP Client

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "osshub": {
      "command": "node",
      "args": ["/path/to/osshub/dist/index.js"],
      "env": {}
    }
  }
}

Cursor Configuration

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "osshub": {
      "command": "node",
      "args": ["/path/to/osshub/dist/index.js", "--config=/path/to/osshub.toml"]
    }
  }
}

Configuration

TOML Configuration (Recommended)

# Huawei Cloud OBS
[[sources]]
id = "huawei_obs"
type = "obs"
endpoint = "https://obs.cn-east-2.myhuaweicloud.com"
access_key = "your-access-key"
secret_key = "your-secret-key"
region = "cn-east-2"

# Alibaba Cloud OSS
[[sources]]
id = "aliyun_oss"
type = "oss"
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
access_key = "your-access-key"
secret_key = "your-secret-key"
region = "cn-hangzhou"

# AWS S3 / MinIO
[[sources]]
id = "minio"
type = "s3"
endpoint = "http://localhost:9000"
access_key = "minioadmin"
secret_key = "minioadmin"
path_style = true

# Tool configurations (optional)
[[tools]]
name = "list_objects"
source = "huawei_obs"
max_keys = 500

[[tools]]
name = "get_object"
source = "huawei_obs"
max_size = 5242880  # 5MB

Environment Variables

For single-source configuration:

export OSSHUB_TYPE=obs
export OSSHUB_ENDPOINT=https://obs.cn-east-2.myhuaweicloud.com
export OSSHUB_ACCESS_KEY=your-access-key
export OSSHUB_SECRET_KEY=your-secret-key
export OSSHUB_REGION=cn-east-2

Built-in Tools

list_buckets

List all storage buckets in a source.

Tool: list_buckets (or list_buckets_{source_id})
Parameters: None

list_objects

List objects in a bucket with optional filtering.

Tool: list_objects (or list_objects_{source_id})
Parameters:
  - bucket: (required) Bucket name
  - prefix: (optional) Filter by key prefix
  - delimiter: (optional) Delimiter for hierarchical listing
  - max_keys: (optional) Maximum objects to return
  - continuation_token: (optional) Pagination token

get_object

Retrieve object content.

Tool: get_object (or get_object_{source_id})
Parameters:
  - bucket: (required) Bucket name
  - key: (required) Object key
  - max_size: (optional) Maximum content size in bytes

get_object_metadata

Get object metadata without downloading.

Tool: get_object_metadata (or get_object_metadata_{source_id})
Parameters:
  - bucket: (required) Bucket name
  - key: (required) Object key

search_objects

Search objects with advanced filters.

Tool: search_objects (or search_objects_{source_id})
Parameters:
  - bucket: (required) Bucket name
  - prefix: (optional) Key prefix filter
  - suffix: (optional) Key suffix filter
  - extensions: (optional) File extensions [".jpg", ".png"]
  - pattern: (optional) Glob pattern
  - min_size: (optional) Minimum file size
  - max_size: (optional) Maximum file size
  - modified_after: (optional) Modified after date (ISO 8601)
  - modified_before: (optional) Modified before date (ISO 8601)
  - max_results: (optional) Maximum results

Development

# Development mode with hot reload
npm run dev

# HTTP mode development
npm run dev:http

# Run tests
npm test

# Build
npm run build

Provider Support

License

MIT License