OssHub

# OssHub - Universal Object Storage MCP Server OssHub is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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 ```bash # 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: ```toml [[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 ```bash # 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`): ```json { "mcpServers": { "osshub": { "command": "node", "args": ["/path/to/osshub/dist/index.js"], "env": {} } } } ``` #### Cursor Configuration Add to your Cursor MCP settings: ```json { "mcpServers": { "osshub": { "command": "node", "args": ["/path/to/osshub/dist/index.js", "--config=/path/to/osshub.toml"] } } } ``` ## Configuration ### TOML Configuration (Recommended) ```toml # 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: ```bash 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 ```bash # 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 | Provider | Type | Status | SDK | |----------|------|--------|-----| | Huawei Cloud OBS | `obs` | ✅ Supported | [esdk-obs-nodejs](https://github.com/huaweicloud/huaweicloud-sdk-nodejs-obs) v3.25.6 | | Alibaba Cloud OSS | `oss` | ✅ Supported | [ali-oss](https://github.com/ali-sdk/ali-oss) | | AWS S3 | `s3` | ✅ Supported | [@aws-sdk/client-s3](https://github.com/aws/aws-sdk-js-v3) | | MinIO | `s3` | ✅ Supported (S3-Compatible) | @aws-sdk/client-s3 | | Tencent Cloud COS | `cos` | 🚧 Coming Soon | - | | Backblaze B2 | `s3` | ✅ (S3-Compatible) | @aws-sdk/client-s3 | | DigitalOcean Spaces | `s3` | ✅ (S3-Compatible) | @aws-sdk/client-s3 | ## License MIT License