ModelScope MCP Server

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).