modelscope/modelscope-mcp-server

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 descriptions using any AIGC model available on ModelScope
• 📚 Research Paper Search - Search for arXiv papers indexed in ModelScope with comprehensive metadata
• 🔍 Resource Discovery (Coming Soon) - Search for models, datasets, studios and other resources on ModelScope
• 📖 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 Server

# 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

Running the Demo (Optional)

uv run python demo.py

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

Version Bumping

# Patch version (1.0.0 → 1.0.1)
python scripts/bump_version.py patch

# Minor version (1.0.0 → 1.1.0)
python scripts/bump_version.py minor

# Major version (1.0.0 → 2.0.0)
python scripts/bump_version.py major

# Pre-release versions
python scripts/bump_version.py patch --pre dev    # 1.0.1.dev1
python scripts/bump_version.py patch --pre alpha  # 1.0.1a1
python scripts/bump_version.py patch --pre beta   # 1.0.1b1
python scripts/bump_version.py patch --pre rc     # 1.0.1rc1

Release to PyPI

TODO: trigger release from GitHub Actions

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 .