Modelscope Mcp Server

ModelScope MCP Server

English | 中文

为 AI Agent 和聊天机器人提供直接访问 ModelScope 丰富 AI 资源生态的能力。从生成图像到探索前沿模型、数据集、应用和研究论文，这个 MCP 服务让用户通过简单的对话交互即可使用 ModelScope 庞大的工具和服务集合。

如需快速试用或使用托管选项，请访问 ModelScope MCP Plaza 上的项目页面。

✨ 功能

• 🎨 AI 图像生成 - 使用 AIGC 模型根据提示词生成图像（文本转图像），或转换现有图像（图像转图像）
• 🔍 资源发现 - 搜索和发现 ModelScope 资源，包括模型、数据集、工作室（AI 应用）、研究论文和 MCP 服务，并支持高级筛选选项
• 📋 资源详情 - 获取特定资源的详细信息
• 📖 文档搜索 (即将推出) - 对 ModelScope 文档和文章进行语义搜索
• 🚀 Gradio API 集成 (即将推出) - 调用任何预配置 ModelScope 工作室公开的 Gradio API
• 🔐 上下文信息 - 访问当前运行上下文，包括已认证用户的信息和环境详情

🚀 快速开始

1. 获取 API 令牌

1. 访问 ModelScope 并登录账户
2. 前往 [Home] → [Access Tokens] 获取或创建 API 令牌

📖 详细说明请参阅 ModelScope 令牌文档

2. 与 MCP 客户端集成

将以下 JSON 配置添加到 MCP 客户端的配置文件中：

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

或者，也可以使用预构建的 Docker 镜像：

{
  "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"
      }
    }
  }
}

更多详情请参阅 MCP JSON 配置标准。

此格式已在 MCP 生态中广泛采用：

• Cherry Studio：参阅 Cherry Studio MCP 配置
• Claude Desktop：使用 ~/.claude/claude_desktop_config.json
• Cursor：使用 ~/.cursor/mcp.json
• VS Code：使用工作区 .vscode/mcp.json
• 其他客户端：许多兼容 MCP 的应用都遵循此标准

🛠️ 开发

环境设置

1. 克隆并设置：

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

2. 激活环境（或使用 IDE）：

   source .venv/bin/activate  # Linux/macOS
   

3. 设置 API 令牌（令牌设置请参阅“快速开始”部分）：

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

运行演示脚本

运行快速演示，了解此服务的功能：

uv run python demo.py

使用 --full 标志全面演示各项功能：

uv run python demo.py --full

在本地运行服务

# 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

对于 HTTP/SSE 模式，请在 MCP 客户端配置中使用本地 URL 进行连接：

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

也可以使用 MCP Inspector 工具调试服务：

# 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

测试

# 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

🔄 持续集成

此项目使用 GitHub Actions 执行自动化 CI/CD 工作流，并在每次推送和拉取请求时运行：

自动化检查

• ✨ Lint - 使用 pre-commit 钩子进行代码格式化、lint 和风格检查
• 🧪 Test - 在所有支持的 Python 版本上进行全面测试
• 🔍 CodeQL - 安全漏洞扫描和代码质量分析
• 🔒 Gitleaks - 检测密码、API 密钥和令牌等机密信息

本地开发检查

在提交 PR 之前，请在本地运行相同的检查：

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

# Run tests
uv run pytest

在 Actions 标签页中监控 CI 状态。

📦 发布管理

本项目使用 GitHub Actions 进行自动化发布管理。要创建新版本：

1. 更新版本号，使用 bump 脚本：

   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. 提交并打标签（按照脚本输出的指示操作）：

   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. 自动发布 - GitHub Actions 将自动：

   • 创建新的 GitHub Release
   • 将包发布到 PyPI 仓库
   • 构建 Docker 镜像并推送到 GitHub Container Registry

🤝 贡献

我们欢迎贡献！请确保你的 PR：

• 包含相关测试并通过所有 CI 检查
• 为新功能更新文档
• 遵循约定式提交格式

📚 参考资料

• Model Context Protocol - 官方 MCP 文档
• FastMCP v2 - 高性能 MCP 框架
• MCP 示例服务 - 社区服务示例

📜 许可证

本项目基于 Apache License (Version 2.0) 许可。