repo-template

PyPI Query MCP 服务

用于查询 PyPI 软件包信息、依赖项和兼容性的模型上下文协议（MCP）服务。

功能

• 📦 查询 PyPI 软件包信息（名称、版本、描述、依赖项）
• 🐍 检查 Python 版本兼容性
• 🔍 高级依赖分析和递归解析
• 📥 下载软件包并收集依赖项
• 📊 下载统计和受欢迎程度分析
• 🏆 热门软件包排名和趋势
• 🎯 用于引导分析和决策的 MCP 提示词模板
• 🏢 支持私有 PyPI 仓库
• ⚡ 通过缓存实现快速异步操作
• 🛠️ 轻松集成 MCP 客户端

安装

使用 uvx（推荐）

# Run directly with uvx
uvx pypi-query-mcp-server

# Or install and run with specific script
uvx --from pypi-query-mcp-server pypi-query-mcp

使用 pip

# Install from PyPI
pip install pypi-query-mcp-server

# Run the server
python -m pypi_query_mcp.server

从源代码安装

git clone https://github.com/loonghao/pypi-query-mcp-server.git
cd pypi-query-mcp-server
uv sync
uv run pypi-query-mcp

配置

Claude Code（推荐）

使用内置的 MCP 管理功能，将 PyPI Query MCP 服务添加到 Claude Code：

# Add with local scope (project-specific)
claude mcp add pypi uvx pypi-query-mcp-server -s local

# Add with user scope (available across all projects) 
claude mcp add pypi uvx pypi-query-mcp-server -s user

📖 详细指南：请参阅 CLAUDE_CODE_INTEGRATION.md，了解完整的 Claude Code 集成文档。

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pypi-query": {
      "command": "uvx",
      "args": ["--from", "pypi-query-mcp-server", "pypi-query-mcp"],
      "env": {
        "PYPI_INDEX_URL": "https://pypi.org/pypi",
        "PYPI_INDEX_URLS": "https://mirrors.aliyun.com/pypi/simple/,https://pypi.tuna.tsinghua.edu.cn/simple/",
        "PYPI_CACHE_TTL": "3600",
        "PYPI_LOG_LEVEL": "INFO"
      }
    }
  }
}

使用私有仓库

{
  "mcpServers": {
    "pypi-query": {
      "command": "uvx",
      "args": ["--from", "pypi-query-mcp-server", "pypi-query-mcp"],
      "env": {
        "PYPI_INDEX_URL": "https://pypi.org/pypi",
        "PYPI_PRIVATE_PYPI_URL": "https://private.pypi.company.com",
        "PYPI_PRIVATE_PYPI_USERNAME": "your_username",
        "PYPI_PRIVATE_PYPI_PASSWORD": "your_password",
        "PYPI_CACHE_TTL": "3600"
      }
    }
  }
}

Cline

添加到 Cline MCP 设置（cline_mcp_settings.json）：

{
  "mcpServers": {
    "pypi-query": {
      "command": "uvx",
      "args": ["--from", "pypi-query-mcp-server", "pypi-query-mcp"],
      "env": {
        "PYPI_INDEX_URL": "https://pypi.org/simple/",
        "CACHE_TTL": "3600"
      }
    }
  }
}

Cursor

添加到 Cursor MCP 配置（.cursor/mcp.json）：

{
  "mcpServers": {
    "pypi-query": {
      "command": "uvx",
      "args": ["--from", "pypi-query-mcp-server", "pypi-query-mcp"],
      "env": {
        "PYPI_INDEX_URL": "https://pypi.org/simple/",
        "CACHE_TTL": "3600"
      }
    }
  }
}

Windsurf

添加到 Windsurf MCP 配置（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "pypi-query": {
      "command": "uvx",
      "args": ["--from", "pypi-query-mcp-server", "pypi-query-mcp"],
      "env": {
        "PYPI_INDEX_URL": "https://pypi.org/simple/",
        "CACHE_TTL": "3600"
      }
    }
  }
}

环境变量

基本配置

• PYPI_INDEX_URL：主 PyPI 索引 URL（默认值：https://pypi.org/pypi）
• PYPI_CACHE_TTL：缓存生存时间，单位为秒（默认值：3600）
• PYPI_LOG_LEVEL：日志级别（默认值：INFO）
• PYPI_REQUEST_TIMEOUT：HTTP 请求超时时间，单位为秒（默认值：30.0）

支持多个镜像源

• PYPI_INDEX_URLS：其他 PyPI 索引 URL（逗号分隔，可选）
• PYPI_EXTRA_INDEX_URLS：用于回退的额外 PyPI 索引 URL（逗号分隔，可选）

支持私有仓库

• PYPI_PRIVATE_PYPI_URL：私有 PyPI 仓库 URL（可选）
• PYPI_PRIVATE_PYPI_USERNAME：私有 PyPI 用户名（可选）
• PYPI_PRIVATE_PYPI_PASSWORD：私有 PyPI 密码（可选）

高级依赖分析

• PYPI_DEPENDENCY_MAX_DEPTH：递归依赖分析的最大深度（默认值：5）
• PYPI_DEPENDENCY_MAX_CONCURRENT：并发依赖查询的最大数量（默认值：10）
• PYPI_ENABLE_SECURITY_ANALYSIS：启用安全漏洞分析（默认值：false）

配置示例

# Use multiple mirror sources for better availability
export PYPI_INDEX_URL="https://pypi.org/pypi"
export PYPI_INDEX_URLS="https://mirrors.aliyun.com/pypi/simple/,https://pypi.tuna.tsinghua.edu.cn/simple/"
export PYPI_EXTRA_INDEX_URLS="https://test.pypi.org/simple/"

# Private repository configuration
export PYPI_PRIVATE_PYPI_URL="https://private.pypi.company.com"
export PYPI_PRIVATE_PYPI_USERNAME="your_username"
export PYPI_PRIVATE_PYPI_PASSWORD="your_password"

可用的 MCP 工具

该服务提供以下 MCP 工具：

核心软件包信息

1. get_package_info - 获取全面的软件包信息
2. get_package_versions - 列出软件包的所有可用版本
3. get_package_dependencies - 分析软件包依赖项

Python 兼容性

4. check_package_python_compatibility - 检查 Python 版本兼容性
5. get_package_compatible_python_versions - 获取所有兼容的 Python 版本

高级依赖分析

6. resolve_dependencies - 递归解析软件包的所有依赖项并进行详细分析
7. download_package - 将软件包及其所有依赖项下载到本地目录

下载统计与受欢迎程度

8. get_download_statistics - 获取任意软件包的全面下载统计信息
9. get_download_trends - 分析下载趋势和时间序列数据（最近 180 天）
10. get_top_downloaded_packages - 按下载量获取最受欢迎的软件包

MCP 提示词模板

11. analyze_package_quality - 生成全面的软件包质量分析提示词
12. compare_packages - 生成详细的软件包比较提示词
13. suggest_alternatives - 生成用于查找软件包替代方案的提示词
14. resolve_dependency_conflicts - 生成用于解决依赖冲突的提示词
15. plan_version_upgrade - 生成用于规划软件包版本升级的提示词
16. audit_security_risks - 生成用于安全风险审计的提示词
17. plan_package_migration - 生成全面的软件包迁移计划提示词
18. generate_migration_checklist - 生成详细的迁移检查清单提示词

环境分析模板

19. analyze_environment_dependencies - 生成用于分析当前环境依赖项的提示词
20. check_outdated_packages - 生成用于检查过时软件包及其更新优先级的提示词
21. generate_update_plan - 生成用于制定全面软件包更新计划的提示词

趋势分析模板

22. analyze_daily_trends - 生成用于分析每日 PyPI 下载趋势的提示词
23. find_trending_packages - 生成用于发现一段时间内热门软件包的提示词
24. track_package_updates - 生成用于跟踪近期软件包更新和发布的提示词

📖 详细了解提示词模板：请参阅 PROMPT_TEMPLATES.md，了解详细文档和示例。

使用示例

在 MCP 客户端（Claude Desktop、Cline、Cursor、Windsurf）中完成配置后，你可以提出如下问题：

基本软件包查询

• “Django 4.2 有哪些依赖项？”
• “FastAPI 是否兼容 Python 3.9？”
• “显示 requests 软件包的所有版本”
• “numpy 支持哪些 Python 版本？”
• “获取 pandas 软件包的详细信息”

高级依赖分析

• “请帮我分析 PySide2 在 Python 3.10 下的完整依赖树”
• “解析 Django 的所有依赖项，包括开发依赖项”
• “FastAPI 的所有传递依赖项有哪些？”

软件包下载

• “请帮我将 PySide2 及其所有依赖项下载到我的本地计算机，适用于 Python 3.10”
• “将 requests 软件包及其所有依赖项下载到 ./downloads 文件夹”
• “收集 Django 开发所需的所有软件包”

下载统计与受欢迎程度分析

• “requests 软件包本月的下载统计数据是什么？”
• “显示 numpy 过去 180 天的下载趋势”
• “今天下载量最高的 10 个 Python 软件包是什么？”
• “比较 Django、Flask 和 FastAPI 的受欢迎程度”
• “本周哪个 Web 框架的下载量最高？”

MCP 提示词模板

• “使用 analyze_package_quality 提示词评估 requests 软件包”
• “生成一个比较提示词，比较 Django、FastAPI 和 Flask 在构建 API 方面的表现”
• “为从 Flask 迁移到 FastAPI 创建迁移计划提示词”
• “用结构化提示词帮我解决依赖冲突”
• “为我的生产环境软件包生成安全审计提示词”

环境分析

• “分析我当前 Python 环境中的依赖项，并检查是否有过时的软件包”
• “检查我的环境中哪些软件包有可用的安全更新”
• “为我的生产环境生成一份采用保守策略的更新计划”
• “帮我识别哪些软件包需要立即更新，哪些可以计划更新”

趋势分析

• “今天下载量最高的 Python 软件包有哪些？”
• “显示本周机器学习领域的热门软件包”
• “跟踪近期的安全更新和新软件包发布”
• “查找 Web 开发领域正在兴起、值得考虑的软件包”

对话示例

用户：“检查 Django 4.2 是否兼容 Python 3.9”

AI 助手：我来为你检查 Django 4.2 与 Python 3.9 的兼容性。

[使用 get_package_info 和 check_package_python_compatibility 工具]

用户：“FastAPI 的主要依赖项有哪些？”

AI 助手：我来获取 FastAPI 的依赖项信息。

[使用 get_package_dependencies 工具]

用户：“显示 requests 包的下载统计数据，并告诉我 requests 和 urllib3 哪个更受欢迎？”

AI 助手：我来获取这两个包的下载统计数据，并比较它们的受欢迎程度。

[分别对这两个包使用 get_download_statistics 工具]

编程使用

# Example: Check if Django is compatible with Python 3.9
result = await mcp_client.call_tool("check_package_python_compatibility", {
    "package_name": "django",
    "target_python_version": "3.9"
})

# Example: Get package information
info = await mcp_client.call_tool("get_package_info", {
    "package_name": "requests"
})

# Example: Get download statistics
stats = await mcp_client.call_tool("get_download_statistics", {
    "package_name": "numpy",
    "period": "month"
})

# Example: Get top downloaded packages
top_packages = await mcp_client.call_tool("get_top_downloaded_packages", {
    "period": "week",
    "limit": 10
})

开发状态

🎉 核心功能已实现，可以使用！

当前实现状态：

• ✅ 基本项目结构
• ✅ 带缓存的 PyPI API 客户端
• ✅ MCP 工具实现（包信息、版本、依赖项）
• ✅ Python 版本兼容性检查
• ✅ 高级依赖项分析和递归解析
• ✅ 下载包并收集依赖项
• ✅ 下载统计和受欢迎程度分析
• ✅ 热门包排名和趋势
• ✅ 支持多平台测试的 CI/CD 流水线
• ⏳ 私有仓库支持（计划中）

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

本项目基于 MIT 许可证授权，详情请参阅 LICENSE 文件。