ModelScope Server

PyPI Version PyPI Downloads Docker GitHub Container Registry License

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

1. Visit ModelScope and sign in to your account
2. 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

1. Clone and Setup:

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

2. Activate Environment (or use your IDE):

   source .venv/bin/activate  # Linux/macOS
   

3. 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:

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

2. 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}
   

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