ModelScope MCP Server

A Model Context Protocol (MCP) server that integrates with ModelScope's ecosystem, providing seamless access to AI models, datasets, apps, papers, and generation capabilities through popular MCP clients.

✨ Features

• 🔐 User Authentication - Retrieve information about the currently authenticated ModelScope user
• 🎨 AI Image Generation - Generate images from text prompts or transform existing images using AIGC models (supports both text-to-image and image-to-image generation)
• 🔍 Model Search - Search for machine learning models on ModelScope with advanced filtering options (task type, author, inference support, etc.)
• 📚 Research Paper Search - Search for arXiv papers indexed in ModelScope with comprehensive metadata
• 📖 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 studio

🚀 Quick Start

1. Get Your API Token

1. Visit ModelScope and sign in to your account
2. Navigate to [Home] → [Access Tokens] to retrieve your default API token or create a new one

📖 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",
        "spadrian/modelscope-mcp-server:latest"
      ],
      "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:

   source .venv/bin/activate  # Linux/macOS
   # or via your IDE

3. Set Your API Token Environment Variable:

   export MODELSCOPE_API_TOKEN="your-api-token"

   Or, you can set the API token in the .env file (under the project root) for convenience:

   MODELSCOPE_API_TOKEN="your-api-token"

Running the Demo Script

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

uv run python demo.py

Use the --full flag to demonstrate all available features:

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:

npx @modelcontextprotocol/inspector uv run modelscope-mcp-server

The above command uses stdio transport by default; you can switch to HTTP or SSE in the Web UI as needed.

Testing

Run the complete test suite:

# Basic test run
uv run pytest

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

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

Code Quality

This project uses pre-commit hooks for automated code formatting, linting, and type checking:

# Install hooks
uv run pre-commit install

# Run all checks manually
uv run pre-commit run --all-files

All PRs must pass these checks and include appropriate tests.

📦 Release Management

TODO: trigger release from GitHub Actions

Release to PyPI

python scripts/pypi_release.py

Release to Docker Hub

docker login

# Release to Docker Hub (will auto-detect buildx or use traditional build)
python scripts/docker_release.py

# Release to Docker Hub (use traditional multi-arch build with manifest)
python scripts/docker_release.py --traditional-multiarch

🤝 Contributing

We welcome contributions! Please ensure that:

1. All PRs include relevant tests and pass the full test suite
2. Code follows our style guidelines (enforced by pre-commit hooks)
3. Documentation is updated for new features
4. Commit messages 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).