ModelScope MCP Server

What is ModelScope MCP Server about?

ModelScope MCP Server empowers AI agents and conversational assistants to interact with ModelScope’s extensive collection of AI models, datasets, studios, research papers, and other resources. It exposes capabilities such as text‑to‑image, image‑to‑image generation, advanced resource search, and access to user context, all through the Model Context Protocol (MCP) interface.

How to use ModelScope MCP Server?

Obtain an API token from ModelScope (Home → Access Tokens).
Configure the MCP client with the server command and token, e.g., using the provided JSON snippet in the README.
Run the server locally with uv run modelscope-mcp-server (default stdio transport) or uv run modelscope-mcp-server --transport http --port 8000 for HTTP/SSE transport.
Connect the client to the local URL http://127.0.0.1:8000/mcp/ or to the Docker image ghcr.io/modelscope/modelscope-mcp-server.
Invoke MCP methods like tools/list, resources/search, or image‑generation calls from any MCP‑compatible tool (Claude Desktop, Cursor, VS Code, etc.).

Key Features of ModelScope MCP Server

AI Image Generation – Text‑to‑image and image‑to‑image generation via AIGC models.
Resource Discovery – Search models, datasets, studios, papers, and other MCP servers with rich filters.
Resource Details – Retrieve comprehensive metadata for any found resource.
Context Information – Access authenticated user info and environment details.
Future Enhancements – Semantic documentation search and Gradio API integration (coming soon).

Use Cases of ModelScope MCP Server

Chatbot augmentation: Enable conversational agents to fetch up‑to‑date models or datasets on‑the‑fly.
Creative workflows: Generate images directly from prompts within an IDE or coding assistant.
Research assistance: Quickly locate relevant papers, code, or datasets while drafting a report.
Enterprise tooling: Integrate ModelScope resources into internal tools without writing custom API calls.

FAQ

Q: Do I need Docker to run the server? A: No. The server runs natively with Python (uv run modelscope-mcp-server). Docker is a convenient alternative.

Q: Which transport protocols are supported? A: Standard stdio (default), HTTP, and SSE transports are available.

Q: How are updates released? A: GitHub Actions automatically create releases, publish to PyPI, and push a Docker image whenever a new version tag is pushed.

Q: Can I use the server with other MCP‑compatible clients? A: Yes. Any client that follows the MCP JSON Configuration Standard can connect by pointing to the server URL or using the command configuration.

Q: Where can I find the API token? A: In the ModelScope web UI under Home → Access Tokens.

English | 中文

Empowers AI agents and chatbots with direct access to ModelScope's rich ecosystem of AI resources. From generating images to discovering cutting-edge models, datasets, apps and research papers, this MCP server makes ModelScope's vast collection of tools and services accessible through simple conversational interactions.

For a quick trial or a hosted option, visit the project page on the ModelScope MCP Plaza.

✨ Features

🎨 AI Image Generation - Generate images from prompts (text-to-image) or transform existing images (image-to-image) using AIGC models
🔍 Resource Discovery - Search and discover ModelScope resources including models, datasets, studios (AI apps), research papers, and MCP servers with advanced filtering options
📋 Resource Details - Get comprehensive details for specific resources
📖 Documentation Search (Coming Soon) - Semantic search for ModelScope documentation and articles
🚀 Gradio API Integration (Coming Soon) - Invoke Gradio APIs exposed by any pre-configured ModelScope studios
🔐 Context Information - Access current operational context including authenticated user information and environment details

🚀 Quick Start

1. Get Your API Token

Visit ModelScope and sign in to your account
Navigate to [Home] → [Access Tokens] to retrieve or create your API token

📖 For detailed instructions, refer to the ModelScope Token Documentation

2. Integration with MCP Clients

Add the following JSON configuration to your MCP client's configuration file:

{
  "mcpServers": {
    "modelscope-mcp-server": {
      "command": "uvx",
      "args": ["modelscope-mcp-server"],
      "env": {
        "MODELSCOPE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Or, you can use the pre-built Docker image:

{
  "mcpServers": {
    "modelscope-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MODELSCOPE_API_TOKEN",
        "ghcr.io/modelscope/modelscope-mcp-server"
      ],
      "env": {
        "MODELSCOPE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Refer to the MCP JSON Configuration Standard for more details.

This format is widely adopted across the MCP ecosystem:

Cherry Studio: See Cherry Studio MCP Configuration
Claude Desktop: Uses ~/.claude/claude_desktop_config.json
Cursor: Uses ~/.cursor/mcp.json
VS Code: Uses workspace .vscode/mcp.json
Other clients: Many MCP-compatible applications follow this standard

🛠️ Development

Environment Setup

Clone and Setup:

git clone https://github.com/modelscope/modelscope-mcp-server.git
cd modelscope-mcp-server
uv sync

Activate Environment (or use your IDE):

source .venv/bin/activate  # Linux/macOS

Set Your API Token (see Quick Start section for token setup):

export MODELSCOPE_API_TOKEN="your-api-token"
# Or create .env file: echo 'MODELSCOPE_API_TOKEN="your-api-token"' > .env

Running the Demo Script

Run a quick demo to explore the server's capabilities:

uv run python demo.py

Use the --full flag for comprehensive feature demonstration:

uv run python demo.py --full

Running the Server Locally

# Standard stdio transport (default)
uv run modelscope-mcp-server

# Streamable HTTP transport for web integration
uv run modelscope-mcp-server --transport http

# HTTP/SSE transport with custom port (default: 8000)
uv run modelscope-mcp-server --transport [http/sse] --port 8080

For HTTP/SSE mode, connect using a local URL in your MCP client configuration:

{
  "mcpServers": {
    "modelscope-mcp-server": {
      "url": "http://127.0.0.1:8000/mcp/"
    }
  }
}

You can also debug the server using the MCP Inspector tool:

# Run in UI mode with stdio transport (can switch to HTTP/SSE in the Web UI as needed)
npx @modelcontextprotocol/inspector uv run modelscope-mcp-server

# Run in CLI mode with HTTP transport (can do operations across tools, resources, and prompts)
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp/ --transport http --method tools/list

Testing

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_search_papers.py

# With coverage report
uv run pytest --cov=src --cov-report=html

🔄 Continuous Integration

This project uses GitHub Actions for automated CI/CD workflows that run on every push and pull request:

Automated Checks

✨ Lint - Code formatting, linting, and style checks using pre-commit hooks
🧪 Test - Comprehensive testing across all supported Python versions
🔍 CodeQL - Security vulnerability scanning and code quality analysis
🔒 Gitleaks - Detecting secrets like passwords, API keys, and tokens

Local Development Checks

Run the same checks locally before submitting PRs:

# Install and run pre-commit hooks
uv run pre-commit install
uv run pre-commit run --all-files

# Run tests
uv run pytest

Monitor CI status in the Actions tab.

📦 Release Management

This project uses GitHub Actions for automated release management. To create a new release:

Update version using the bump script:

uv run python scripts/bump_version.py [patch|minor|major]
# Or set specific version: uv run python scripts/bump_version.py set 1.2.3.dev1

Commit and tag (follow the script's output instructions):

git add src/modelscope_mcp_server/_version.py
git commit -m "chore: bump version to v{version}"
git tag v{version} && git push origin v{version}

Automated publishing - GitHub Actions will automatically:
- Create a new GitHub Release
- Publish package to PyPI repository
- Build and push Docker image to GitHub Container Registry

🤝 Contributing

We welcome contributions! Please ensure your PRs:

Include relevant tests and pass all CI checks
Update documentation for new features
Follow conventional commit format

📚 References

Model Context Protocol - Official MCP documentation
FastMCP v2 - High-performance MCP framework
MCP Example Servers - Community server examples

📜 License

This project is licensed under the Apache License (Version 2.0).

ModelScope MCP Server