ModelScope MCP 服务器

English | 中文

通过直接访问 ModelScope 丰富的 AI 资源生态系统，为 AI 代理和聊天机器人赋能。从生成图像到发现前沿模型、数据集、应用程序和研究论文，此 MCP 服务器使 ModelScope 的大量工具和服务可以通过简单的对话交互访问。

✨ 特性

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

🚀 快速开始

1. 获取您的 API 令牌

1. 访问 ModelScope 并登录您的账户
2. 导航至 [主页] → [访问令牌] 以检索或创建您的 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 之前，请先在本地运行相同的检查：

bash

# 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 脚本：

bash

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

1. 提交并打标签（按照脚本输出的指示操作）：

bash

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}

1. 自动化发布 - GitHub Actions 将自动执行以下操作：
   • 创建一个新的 GitHub 发布版本
   • 将包发布到 PyPI 仓库
   • 构建并将 Docker 镜像推送到 GitHub 容器注册表

🤝 贡献

我们欢迎贡献！请确保您的 PR 满足以下条件：

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

📚 参考资料

• 模型上下文协议 (MCP) - 官方 MCP 文档
• FastMCP v2 - 高性能 MCP 框架
• MCP 示例服务器 - 社区服务器示例

📜 许可证

本项目采用 Apache 许可证 (版本 2.0)。