ModelScope Unified Operations Entrypoint

Verified with modelscope 1.37.1, Python 3.12 (2026-06-23)

Operate the full range of ModelScope platform capabilities through OpenAPI, CLI, and SDK, covering Hub (models/datasets), Studio, MCP services, and the Skills Center (Skills). This Skill serves as a quick-reference entrypoint; complex operational workflows require the dedicated Skill.

Requirements

pip install modelscope

pip install modelscope installs both the SDK (modelscope.hub.api.HubApi) and two sets of command-line entrypoints:

ms (driven by modelscope_hub v0.1.2): Hub / Studio / MCP operations (download/upload/create/deploy/mcp/secret/…). This document uses ms uniformly for Hub/Studio/MCP commands.
modelscope (legacy CLI): additionally provides commands such as skills (modelscope skills add) — ms (modelscope_hub) does not have a skills subcommand.

⚠️ Both packages register the ms and modelscope entrypoints; which one actually takes effect depends on install order. If an entrypoint lacks a required subcommand (typically: ms has no skills), switch to the other entrypoint, or use the SDK / curl install.sh (see §9 and references/skills-center.md).

Authentication

All operations rely on unified authentication:

# Environment variable
export MODELSCOPE_API_KEY="your_token"

# Token retrieval URL
# $MODELSCOPE_ENDPOINT/my/myaccesstoken

| Operation method | Authentication method | |----------|----------| | OpenAPI | Authorization: Bearer $MODELSCOPE_API_KEY | | CLI | ms login --token $MODELSCOPE_API_KEY | | SDK | api.login(access_token=os.environ['MODELSCOPE_API_KEY']) |

Site selection & endpoint routing

ModelScope runs two independent sites — the domestic site https://modelscope.cn (default) and the international site https://www.modelscope.ai. They have separate accounts, access tokens, and content catalogs. Every operation here targets whichever site $MODELSCOPE_ENDPOINT points to.

Pick the target site (intent analysis)

Respect an existing setting — if MODELSCOPE_ENDPOINT is already exported, use it as-is.
Explicit intent — "international" / "modelscope.ai" / "overseas" ⇒ international; "domestic" / "modelscope.cn" ⇒ domestic.
Match the token or URL the user provides — a modelscope.ai token or link ⇒ international (and vice versa).
Default to the domestic site (https://modelscope.cn) when there is no signal; ask the user if the task clearly targets one audience but the site is ambiguous.

Configure

# Export the endpoint first — the examples below reference $MODELSCOPE_ENDPOINT:
export MODELSCOPE_ENDPOINT="https://modelscope.cn"          # domestic (default)
# export MODELSCOPE_ENDPOINT="https://www.modelscope.ai"   # international
export MODELSCOPE_API_KEY="<token issued by THAT site>"     # tokens are site-scoped — must match the site

One MODELSCOPE_ENDPOINT reroutes everything derived from it: the OpenAPI base ($MODELSCOPE_ENDPOINT/openapi/v1), the ms CLI, the modelscope_hub SDK, and git push URLs ($MODELSCOPE_ENDPOINT/{models,datasets,studios}/…). Resolution precedence (modelscope_hub): explicit arg > MODELSCOPE_ENDPOINT > MODELSCOPE_DOMAIN (deprecated) > default https://modelscope.cn. For public reads you may also set MODELSCOPE_PREFER_AI_SITE=true to try .ai before .cn.

Tokens are site-scoped (stored per endpoint host): a modelscope.cn token will not authorize write/private operations on modelscope.ai. Get each site's token from $MODELSCOPE_ENDPOINT/my/myaccesstoken.

All examples below use $MODELSCOPE_ENDPOINT/openapi/v1 as the base — export MODELSCOPE_ENDPOINT first (raw curl needs it set; the ms CLI and SDK additionally fall back to https://modelscope.cn when it is unset). A few marketplace/doc links (skills install.sh, /docs/…) show the domestic host — swap to your site's host when targeting international.

Conventions

| Item | Value | |------|-----| | OpenAPI Base URL | $MODELSCOPE_ENDPOINT/openapi/v1 (default https://modelscope.cn) | | Success response | {"success": true, "data": {...}, "request_id": "..."} | | Error response | {"success": false, "code": "ERROR_CODE", "message": "..."} | | HTTP status codes | 200 success / 401 unauthorized / 404 not found / 500 server error | | Default branch | master (not main) | | Pagination limit | page_number × page_size ≤ 3000 |

Quick Decision Guide

User wants to...
│
├─── Hub: models/datasets ─────────────────────────────
│   ├── Search models/datasets → OpenAPI GET /models or /datasets
│   ├── View details → GET /models/{owner}/{repo} or SDK model_info()
│   ├── Download → CLI: ms download owner/repo
│   ├── Upload → CLI: ms upload owner/repo ./local
│   ├── Create repository → CLI: ms create owner/repo
│   ├── Browse files → SDK: api.get_model_files()
│   ├── Inspect dataset → uv run scripts/ms_inspect_dataset.py
│   └── Version management → SDK: api.get_model_branches_and_tags()
│
├─── Studio ──────────────────────────────
│   ├── Create Studio → POST /studios or CLI: ms create owner/repo --repo-type studio
│   ├── Deploy/restart → CLI: ms deploy owner/repo --repo-type studio
│   ├── View status → GET /studios/{owner}/{repo}
│   ├── View logs → CLI: ms logs owner/repo --log-type run
│   ├── Stop → CLI: ms stop owner/repo --repo-type studio
│   ├── Update settings → CLI: ms settings owner/repo key=value --repo-type studio
│   ├── Available configs → GET /studios/hardware, /studios/sdk-versions, /studios/base-images
│   ├── Plaintext variables → GET/POST/PUT/DELETE /studios/{owner}/{repo}/variables
│   ├── Secrets → GET/POST/PUT/DELETE /studios/{owner}/{repo}/secrets (or ms secret ...)
│   └── Full deployment workflow → see ms-studio-deploy
│
├─── MCP: service management ──────────────────────────────
│   ├── Search MCP services → CLI: ms mcp list --search "..."
│   ├── View details → CLI: ms mcp info @author/name
│   ├── Deploy service → CLI: ms mcp deploy @author/name
│   ├── Undeploy service → CLI: ms mcp undeploy @author/name
│   ├── My deployed → GET /mcp/servers/operational
│   └── IDE configuration / full orchestration → see references/mcp-services.md
│
├─── Skills: Skills Center ────────────────────────────
│   ├── Search skills → GET /skills?search=...
│   ├── View details → GET /skills/{id}
│   ├── Install skill → modelscope skills add @author/skill-name (legacy CLI; ms has no skills)
│   ├── Publish skill → POST /files/upload + POST /skills
│   ├── Update skill → PATCH /skills/{owner}/{skill_name}/settings
│   └── Category system / packaging spec / full publish → see references/skills-center.md
│
├─── User info ───────────────────────────────────
│   └── GET /users/me
│
└─── Not supported ─────────────────────────────────────
    ├── Pull Request (ModelScope has no PR system)
    └── Delete tags/branches (no API)

1. Resource Search

OpenAPI Method

Search models:

curl "$MODELSCOPE_ENDPOINT/openapi/v1/models?search=Qwen&sort=downloads&page_size=20" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

Search parameters:

| Parameter | Description | Example | |------|------|------| | search | Keyword | "Qwen", "text generation" | | owner | Author/organization | "Qwen", "ZhipuAI" | | sort | Sort | default, downloads, likes, last_modified | | page_size | Items per page (max 50) | 20 | | filter.task | Task type | text-generation, image-captioning | | filter.library | Framework | pytorch, safetensors, diffusers | | filter.model_type | Model type | qwen3_moe, glm4v, llama | | filter.license | License | Apache License 2.0, MIT License |

Common filter combinations:

# PyTorch text-generation models, sorted by downloads
/models?filter.library=pytorch&filter.task=text-generation&sort=downloads

# All models from a specific author
/models?owner=Qwen&sort=last_modified

Search datasets:

curl "$MODELSCOPE_ENDPOINT/openapi/v1/datasets?search=dialogue&sort=downloads&page_size=10" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

OpenAPI response structure (model list):

{"data": {"models": [{"id": "Qwen/...", "downloads": N, "likes": N, "license": "...", "tasks": [...]}], "total_count": N}}

SDK Method

from modelscope.hub.api import HubApi

api = HubApi()

# Search models → dict{"Models": [...], "TotalCount": N}
result = api.list_models(owner_or_group="Qwen", page_number=1, page_size=20)
for m in result["Models"]:
    print(f"{m['Path']} ({m['Downloads']} downloads)")

# Search datasets → dict{"datasets": [...], "total_count": N}
result = api.list_datasets(owner_or_group="AI-ModelScope", page_number=1, page_size=20)
for d in result["datasets"]:
    print(f"{d['id']} ({d['downloads']} downloads)")

SDK vs OpenAPI field name differences: SDK list_models returns PascalCase (Path, Downloads), while OpenAPI /models returns snake_case (id, downloads). list_datasets is snake_case on both sides.

2. View Details

OpenAPI Method

# Model details
curl "$MODELSCOPE_ENDPOINT/openapi/v1/models/Qwen/Qwen2.5-72B-Instruct" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

# Dataset details
curl "$MODELSCOPE_ENDPOINT/openapi/v1/datasets/AI-ModelScope/alpaca-gpt4-data-zh" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

SDK Method (more complete info)

info = api.model_info("Qwen/Qwen2.5-72B-Instruct")
# info.readme_content  - Full README text
# info.tags            - Tag list
# info.downloads       - Download count
# info.siblings        - File list (incl. rfilename, size, sha)
# info.visibility      - Visibility (1=private, 5=public)

info = api.dataset_info("AI-ModelScope/alpaca-gpt4-data-zh")

Get User Info

curl "$MODELSCOPE_ENDPOINT/openapi/v1/users/me" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

3. Repository Management

Create Repository

# CLI (--repo-type required)
ms create owner/repo-name --repo-type model
ms create owner/repo-name --repo-type model --visibility private
ms create owner/dataset-name --repo-type dataset

# SDK: general creation — note that create_repo's visibility uses the string "public"/"private"
api.create_repo(
    repo_id="owner/repo-name",
    repo_type="model",            # "model" or "dataset"
    visibility="public",          # "public" or "private" (string, not integer)
    license="Apache License 2.0",
    exist_ok=True
)

# Model-specific — create_model/create_dataset visibility uses integers 1=private, 5=public
api.create_model(model_id="owner/model-name", visibility=5)

# Dataset-specific
api.create_dataset(
    dataset_name="dataset-name",
    namespace="owner",
    visibility=5
)

# AIGC/LoRA models: via the SDK's aigc_model parameter (create_repo/create_model); no corresponding CLI flag

Check Whether a Repository Exists

exists = api.repo_exists(repo_id="owner/repo", repo_type="model")

Set Visibility

# visibility uses the string "public" / "private" (not an integer)
api.set_repo_visibility(repo_id="owner/repo", repo_type="model", visibility="private")

Delete Repository

⚠️ Repository deletion has been restricted by the platform to the web console only: api.delete_repo(...) returns 401 under token authentication ("Deletion is restricted to web console") and cannot be deleted programmatically. Please perform this operation on the web at https://modelscope.cn.

4. File Operations

List Files

files = api.get_model_files(
    model_id="Qwen/Qwen2.5-7B-Instruct",
    revision="master",
    recursive=True
)
for f in files:
    print(f"  {f['Name']}  Size: {f.get('Size', 'unknown')}")

# Check whether a file exists
exists = api.file_exists(repo_id="owner/repo", filename="config.json", revision="master")

Read File Content

# Use the helper script
uv run scripts/ms_read_file.py \
    --repo_id "Qwen/Qwen2.5-7B-Instruct" \
    --file_path "config.json" \
    --repo_type model

# SDK manual download
from modelscope.hub.file_download import model_file_download

local_path = model_file_download(
    model_id="Qwen/Qwen2.5-7B-Instruct",
    file_path="config.json"
)

Download Models/Files

# CLI: download the full model
ms download Qwen/Qwen2.5-7B-Instruct

# CLI: download a specific file
ms download Qwen/Qwen2.5-7B-Instruct config.json

# CLI: filter by pattern
ms download Qwen/Qwen2.5-7B-Instruct --include "*.json" --exclude "*.safetensors"

# SDK: download snapshot
from modelscope import snapshot_download

local_dir = snapshot_download(
    model_id="Qwen/Qwen2.5-7B-Instruct",
    cache_dir="/tmp/models",
    allow_file_pattern=["*.json", "*.md"],    # Download only matching files
    ignore_file_pattern=["*.safetensors"]     # Exclude large files
)

# Download a single dataset file
from modelscope.hub.file_download import dataset_file_download
local_path = dataset_file_download(dataset_id="owner/dataset", file_path="data/train.jsonl")

Upload Files

# CLI: upload a directory
ms upload owner/repo ./local-dir

# SDK: upload a single file
api.upload_file(
    path_or_fileobj="/path/to/file.txt",
    path_in_repo="data/file.txt",
    repo_id="owner/repo",
    repo_type="model",
    commit_message="Add data file"
)

# SDK: upload a directory
api.upload_folder(
    repo_id="owner/repo",
    folder_path="/path/to/folder",
    commit_message="Upload model files",
    repo_type="model",
    ignore_patterns=["*.pyc", "__pycache__", ".git"]
)

Delete Files

⚠️ File deletion is likewise restricted to the web console only: api.delete_files(...) has no effect under token authentication (the old SDK silently returns failed_files while the files remain; the new modelscope_hub reports 401 "Deletion is restricted to web console"). To delete files, go to the web console at https://modelscope.cn, or clone the repository (git), delete the files, then commit and push.

Atomic Multi-File Commit

from modelscope.hub.api import CommitOperationAdd

operations = [
    CommitOperationAdd(path_in_repo="config.json", path_or_fileobj="/local/config.json"),
    CommitOperationAdd(path_in_repo="README.md", path_or_fileobj="/local/README.md"),
]
api.create_commit(
    repo_id="owner/repo", operations=operations,
    commit_message="Update config and docs", repo_type="model"
)

Notebook / Tutorial Adaptation

When migrating from HuggingFace, Colab, or GitHub tutorials to ModelScope, the core task is replacing the asset sources:

Model download: Replace hf_hub_download / HF snapshot_download with the ms download above or the SDK snapshot_download
Dataset loading: Replace datasets.load_dataset("hf_id") with MsDataset.load("ms_id") or dataset_snapshot_download
Repository search: Use OpenAPI or the SDK to search for equivalent resources on ModelScope

For the complete adaptation workflow (asset mapping, license checking, execution validation), see: modelscope skills add VoyagerX/modelscope-notebook-develop

Error-Prevention Comparison

# ✅ CORRECT — Explicitly specifying repo_type improves readability
api.upload_folder(repo_id="owner/repo", folder_path="./local", repo_type="model")

# ⚠️ Also works (repo_type defaults to model), but explicit is recommended
api.upload_folder(repo_id="owner/repo", folder_path="./local")

# ✅ CORRECT — Use the model_id parameter
snapshot_download(model_id="Qwen/Qwen2.5-7B-Instruct")

# ⚠️ repo_id also works, but model_id is semantically clearer
snapshot_download(repo_id="Qwen/Qwen2.5-7B-Instruct")

5. Dataset Inspection

ModelScope currently supports dataset exploration through a combination of the API/SDK/CLI described above:

Metadata: api.dataset_info() or OpenAPI GET /datasets/{id} → description, tags, file list
File browsing: api.get_dataset_files() → list all files and their sizes
Content reading: ms_read_file.py --repo_type dataset → download and view the content of a single file
Deep inspection: ms_inspect_dataset.py → wraps the above capabilities + MsDataset.load to perform schema extraction and sample preview in one step (requires downloading data locally)

Using the Helper Script

Use the helper script scripts/ms_inspect_dataset.py to quickly understand a dataset's file structure, field schema, and sample content. Internally the script calls the SDK (HubApi.dataset_info + MsDataset.load) to perform the operations.

The examples below use uv run (zero-config); in an environment with modelscope already installed you can also run python scripts/ms_inspect_dataset.py ... directly — see "Helper Scripts" at the end of the document.

# Full inspection (file structure + schema + sample preview)
uv run scripts/ms_inspect_dataset.py \
    --dataset_id "AI-ModelScope/alpaca-gpt4-data-zh" \
    --operation full

# View file structure only
uv run scripts/ms_inspect_dataset.py \
    --dataset_id "AI-ModelScope/alpaca-gpt4-data-zh" \
    --operation overview

# View schema only
uv run scripts/ms_inspect_dataset.py \
    --dataset_id "AI-ModelScope/alpaca-gpt4-data-zh" \
    --operation schema --split train

# Preview samples only
uv run scripts/ms_inspect_dataset.py \
    --dataset_id "AI-ModelScope/alpaca-gpt4-data-zh" \
    --operation samples --num_samples 5

6. Version Control

List Branches and Tags

branches, tags = api.get_model_branches_and_tags(model_id="Qwen/Qwen2.5-7B-Instruct")

# Detailed info (incl. commit hash, timestamps, etc.)
details = api.get_model_branches_and_tags_details(model_id="owner/repo")

Validate Revision

# First argument is model_id (not repo_id)
valid = api.get_valid_revision(model_id="owner/repo", revision="v1.0")

Create Tag

api.create_model_tag(
    model_id="owner/model-name",
    tag_name="v1.0"
)

View Commit History

commits = api.list_repo_commits(
    repo_id="owner/repo",
    repo_type="model",
    revision="master",
    page_number=1,
    page_size=20
)

Known Limitations

| Operation | Status | Notes | |------|------|------| | List branches/tags | ✅ | get_model_branches_and_tags() | | Create tag | ✅ | create_model_tag() | | Delete tag | ❌ | No API | | Create branch | ❌ | Requires git clone → git checkout -b → git push | | Delete branch | ❌ | No API | | Merge branch | ❌ | ModelScope has no PR system |

7. Studio Operations

For the complete deployment workflow (including code sync, diagnosis and repair) → ms-studio-deploy (OpenAPI is the source of truth, CLI is an equivalent alias)

The CLI is driven by modelscope_hub and is a 1:1 thin wrapper around OpenAPI; the API-first Python entrypoint is from modelscope_hub import HubApi. If the agent already has the studio-mcp tools configured, you can also use the MCP tools (createStudio, deployStudio, etc.).

Create Studio

# CLI
ms create USERNAME/my-app --repo-type studio --sdk-type gradio --private

# OpenAPI
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/studios" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner": "USERNAME", "repo_name": "my-app", "sdk_type": "gradio", "visibility": "private"}'

| sdk_type | Use case | |----------|----------| | gradio | Gradio app (entrypoint app.py) | | streamlit | Streamlit app | | docker | Custom Docker (port must be 7860) | | static | Pure static website (already built) |

Query Available Configs

curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/hardware?sdk_type=gradio" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"
curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/sdk-versions?sdk_type=gradio" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"
curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/base-images" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

When a Studio already exists, you can append &studio=USERNAME/my-app to the hardware query. hardware uses the name of the returned items; the paid-resource format is paid/<InstanceType>. Gradio sdk_version uses the version of the returned items, and base_image uses the name of the returned items.

Paid-resource authorization requirement: Using paid/<InstanceType> or a returned item with resource_type=paid incurs charges on the Alibaba Cloud account bound to the user's ModelScope; you must first clearly inform the user and obtain their explicit authorization before creating, updating settings, or redeploying.

Deploy/Restart

# CLI
ms deploy USERNAME/my-app --repo-type studio

# OpenAPI
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/deploy" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

View Status and Logs

# CLI
ms logs USERNAME/my-app --log-type run
ms logs USERNAME/my-app --log-type build  # Docker type

# OpenAPI
curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"
curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/logs/run" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

Stop

# CLI
ms stop USERNAME/my-app --repo-type studio

# OpenAPI
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/stop" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

Update Settings

# CLI
ms settings USERNAME/my-app --repo-type studio display_name="New name" private=false

# OpenAPI
curl -X PATCH "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/settings" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New name", "visibility": "public", "sdk_type": "gradio"}'

Updatable fields: display_name, description, visibility, sdk_type, sdk_version, base_image, hardware, license. private is deprecated; OpenAPI prefers visibility.

Variable Management

Plaintext variables return both key and value, and are used only for non-sensitive configuration:

curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/variables" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/variables" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "GRADIO_TEMP_DIR", "value": "/tmp/gradio"}'
curl -X PUT "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/variables" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "GRADIO_TEMP_DIR", "value": "/mnt/workspace/tmp"}'
curl -X DELETE "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/variables" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "GRADIO_TEMP_DIR"}'

Secrets return only the key, not the value, and are used for sensitive information such as API keys, tokens, and passwords:

# CLI
ms secret list USERNAME/my-app
ms secret add USERNAME/my-app API_KEY sk-xxx
ms secret update USERNAME/my-app API_KEY new-value
ms secret delete USERNAME/my-app API_KEY

# OpenAPI
curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/secrets" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/secrets" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY", "value": "sk-xxx"}'
curl -X PUT "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/secrets" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY", "value": "new-value"}'
# Delete: put the key in the body, not as a path parameter (DELETE .../{key} returns 404)
curl -X DELETE "$MODELSCOPE_ENDPOINT/openapi/v1/studios/USERNAME/my-app/secrets" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY"}'

Code Sync

git remote add modelscope https://oauth2:${MODELSCOPE_API_KEY}@www.modelscope.cn/studios/${owner}/${repo}.git
git push -u modelscope master

8. MCP Service Operations

Full orchestration, IDE configuration templates, SDK↔OpenAPI field differences → see references/mcp-services.md

Pagination limit page_number × page_size ≤ 100 (server-enforced; exceeding it returns HTTP 403).

Search MCP Services

# CLI
ms mcp list --search "map" --page-size 20

# OpenAPI
curl -X PUT "$MODELSCOPE_ENDPOINT/openapi/v1/mcp/servers" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"search": "map", "page_size": 20}'

View Service Details

# CLI
ms mcp info @amap/amap-maps

# OpenAPI
curl "$MODELSCOPE_ENDPOINT/openapi/v1/mcp/servers/@amap/amap-maps" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

Deploy and Undeploy

When deploying, transport_type is required, with valid values sse / streamable_http; the deployed transport determines the unique URL returned (sse→.../sse, streamable_http→.../mcp).

# CLI (defaults to sse; the other option uses --transport-type streamable_http)
ms mcp deploy @amap/amap-maps
ms mcp undeploy @amap/amap-maps

# OpenAPI (must include transport_type, otherwise HTTP 400 invalid transport_type)
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/mcp/servers/@amap/amap-maps/deploy" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" -H "Content-Type: application/json" \
  -d '{"transport_type": "streamable_http"}'
curl -X DELETE "$MODELSCOPE_ENDPOINT/openapi/v1/mcp/servers/@amap/amap-maps/undeploy" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

View My Deployed Services

curl "$MODELSCOPE_ENDPOINT/openapi/v1/mcp/servers/operational" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

SDK Method

from modelscope.hub.mcp_api import MCPApi

mcp = MCPApi()
mcp.login(access_token="YOUR_TOKEN")

# Search → {"total_count": N, "servers": [{"name", "id", "description"}, ...]}
result = mcp.list_mcp_servers(search="weather", total_count=20)
for s in result["servers"]:
    print(f"{s['id']}: {s['description']}")

# Details → {"name", "description", "id", "servers": [{"type", "url"}, ...]}
detail = mcp.get_mcp_server(server_id="@amap/amap-maps")

# Deployed → {"total_count": N, "servers": [{"name", "id", "mcp_servers": [{"type", "url"}]}, ...]}
operational = mcp.list_operational_mcp_servers()

modelscope.hub.mcp_api.MCPApi supports only search, details, and the deployed list. Use the CLI ms mcp deploy/undeploy or OpenAPI for deploy/undeploy.

9. Skills Center Operations

Category system, packaging spec, complete publish/update/install → see references/skills-center.md

Search Skills

curl "$MODELSCOPE_ENDPOINT/openapi/v1/skills?search=code-review&page_size=20" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"

View Skill Details

curl "$MODELSCOPE_ENDPOINT/openapi/v1/skills/@ModelScope/modelscope-oauth-skill" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY"
# Returns an install_command array containing multiple installation methods

Install Skill

⚠️ skills add is a command of the legacy modelscope CLI; ms (modelscope_hub) does not have skills. If the modelscope/ms entrypoint is overridden by modelscope_hub and reports "no skills command", switch to the curl install.sh or SDK download_skill below (both are the most reliable).

# Option 1: modelscope (legacy) CLI
modelscope skills add @author/skill-name
modelscope skills add @author/skill-name --local_dir ./my-skills   # Specify directory
modelscope skills add @author/skill-1 @author/skill-2              # Batch

# Option 2: Shell script (most reliable, no entrypoint conflicts)
curl -fsSL https://modelscope.cn/skills/install.sh | bash -s -- @author/skill-name
curl -fsSL https://modelscope.cn/skills/install.sh | bash -s -- @author/skill-name --agent cursor

# Option 3: SDK (verified reliable)
from modelscope.hub.mcp_api import MCPApi
MCPApi().download_skill(skill_id="@author/skill-name", local_dir="./my-skills")

modelscope skills add parameters:

| Parameter | Description | |------|------| | skill_ids | Positional argument; one or more skill IDs (format @author/name) | | --local_dir DIR | Install directory (default ~/.agents/skills) | | --token TOKEN | Access Token | | --max-workers N | Number of concurrent downloads (default 8) |

Publish Skill (Quick Reference)

# Step 1: Upload the zip package (the zip root must contain exactly 1 SKILL.md)
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/files/upload" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -F "file=@my-skill.zip" -F "type=skill"
# → Response {"data": {"id": "<uuid>"}}; use data.id as the skill_file for the next step (note the key is id, not file_id)

# Step 2: Create the skill (skill_file takes the data.id from the previous step)
curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/skills" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner": "username", "skill_name": "my-skill", "display_name": "My Skill", "skill_file": "<data.id>", "category": "developer-tools"}'

Update Skill Settings

curl -X PATCH "$MODELSCOPE_ENDPOINT/openapi/v1/skills/{owner}/{skill_name}/settings" \
  -H "Authorization: Bearer $MODELSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New name", "description": "Updated description", "skill_file": "<new_file_id>"}'

Updatable fields: display_name, description, skill_file, tags, source_url, category, license. Not modifiable: owner, skill_name.

Cache Management

ms scan-cache                              # View local cache
ms scan-cache --dir ~/.cache/modelscope    # Specify cache directory
ms clear-cache                             # Clear cache

Known Limitations

| Domain | Limitation | Notes | |----|------|------| | Hub | No PR system | Collaboration is done via direct push | | Hub | No row-level preview API | Requires SDK local loading to inspect | | Hub | Pagination limit | page_number × page_size ≤ 3000; /models single page page_size ≤ 50 | | Hub | Default branch master | Not main | | Hub | Tags cannot be deleted | Can only be created | | Hub | Repository/file deletion via web console only | delete_repo/delete_files return 401 under token; cannot delete programmatically | | Studio | Docker requires real-name verification | Alibaba Cloud account binding | | Studio | Port fixed at 7860 | 8080 cannot be used | | Studio | No programmatic deletion | OpenAPI DELETE /studios/{id} returns 404; SDK/CLI delete_repo is deprecated and does not support studio. Deletion requires the web console; programmatically you can only stop | | MCP | Deployment transport_type required | Valid sse/streamable_http, otherwise HTTP 400 | | MCP | Pagination limit ≤ 100 | page × size > 100 returns HTTP 403 | | MCP | SDK has no deploy/undeploy | Use the CLI ms mcp deploy/undeploy or OpenAPI | | Skills | CLI supports only add | No list/update/remove subcommands yet |

Helper Scripts

| Script | Purpose | |------|------| | scripts/ms_read_file.py | Download and read repository file content | | scripts/ms_inspect_dataset.py | Deeply inspect dataset structure and content |

Two ways to run (choose either):

# Option 1: use python directly in an environment with modelscope installed (consistent with "Requirements")
python scripts/ms_inspect_dataset.py --dataset_id "AI-ModelScope/alpaca-gpt4-data-zh" --operation full

# Option 2: uv zero-config (the script includes PEP 723 inline dependencies and auto-creates a temporary environment)
uv run scripts/ms_inspect_dataset.py --dataset_id "AI-ModelScope/alpaca-gpt4-data-zh" --operation full

Relationship to the Dedicated Skill / references

| Domain | In ms-hub | Expanded location | |----|-----------|----------| | Studio | Quick reference: create/deploy/stop/logs | ms-studio-deploy (full deployment workflow, code sync, diagnosis and repair, API-first) | | MCP | Quick reference: search/details/deploy/undeploy/deployed | references/mcp-services.md (IDE configuration templates, full orchestration, field differences) | | Skills | Quick reference: search/details/install/publish/update | references/skills-center.md (category system, packaging spec, publish workflow) |

0123_yk

ModelScope Unified Operations Entrypoint

Requirements

Authentication

Site selection & endpoint routing

Pick the target site (intent analysis)

Configure

Conventions

Quick Decision Guide

1. Resource Search

OpenAPI Method

SDK Method

2. View Details

OpenAPI Method

SDK Method (more complete info)

Get User Info

3. Repository Management

Create Repository

Check Whether a Repository Exists

Set Visibility

Delete Repository

4. File Operations

List Files

Read File Content

Download Models/Files

Upload Files

Delete Files

Atomic Multi-File Commit

Notebook / Tutorial Adaptation

Error-Prevention Comparison

5. Dataset Inspection

Using the Helper Script

6. Version Control

List Branches and Tags

Validate Revision

Create Tag

View Commit History

Known Limitations

7. Studio Operations

Create Studio

Query Available Configs

Deploy/Restart

View Status and Logs

Stop

Update Settings

Variable Management

Code Sync

8. MCP Service Operations

Search MCP Services

View Service Details

Deploy and Undeploy

View My Deployed Services

SDK Method

9. Skills Center Operations

Search Skills

View Skill Details

Install Skill

Publish Skill (Quick Reference)

Update Skill Settings

Cache Management

Known Limitations

Helper Scripts

Relationship to the Dedicated Skill / references