Skip to main content

Nexus Mods MCP

Python 3.11+ MCP 1.x

查找游戏和 Mod,浏览图集、前置与版本文件,按账户权限下载。


✨ 项目简介

这个非官方本地 stdio 服务通过 Nexus Mods 的 GraphQL 和 REST API 获取资料。项目由游戏域名和该游戏内的 Mod ID 共同定位,例如 skyrimspecialedition 下的 SkyUI 是 12604。可以分别查看项目声明的前置、依赖它的其他作品,以及某个文件版本的依赖。

⚡ 快速开始

前置条件

  • Python 3.11 或更高版本,以及 uv。
  • 公开目录和项目资料可匿名查询。读取受限文件资料或请求下载地址时,可从 Nexus Mods 账户设置 获取个人 API Key。

安装与更新

从 PyPI 安装或更新:

python -m pip install --upgrade glossmod-nexusmods-mcp

安装后运行 nexusmods-mcp,或用 uvx --from glossmod-nexusmods-mcp nexusmods-mcp 直接启动。

从源码运行时,在 nexusmods-mcp 仓库根目录执行:

uv sync --python 3.11

更新仓库源码后,重新执行上面的命令并重启客户端中的服务。若使用已有的 Python 虚拟环境,也可以用 python -m pip install --upgrade . 安装或更新,启动命令为 nexusmods-mcp。

配置客户端

使用账户权限时,在仓库根目录的 .env 中设置以下变量。已有 OAuth 访问令牌也可通过 NEXUSMODS_ACCESS_TOKEN 提供。仅需匿名查询时,直接从下方 args 中移除 "--env-file", ".env" 即可启动。

NEXUSMODS_API_KEY='替换为你的个人 API Key'
# 可选;默认目录为 ~/Downloads/NexusMods
# NEXUSMODS_DOWNLOAD_DIR=E:/Downloads/NexusMods

将以下条目加入使用 mcpServers 格式的客户端,把 --directory 后的示例路径替换为本仓库的绝对路径。使用 VS Code 的 .vscode/mcp.json 时,顶层键使用 servers。

{
  "mcpServers": {
    "nexusmods-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "E:/GitHub/mcp/nexusmods-mcp", "run", "--no-sync", "--env-file", ".env", "nexusmods-mcp"]
    }
  }
}

第一次调用

试试「查找《Skyrim Special Edition》的 SkyUI,给我项目主页和图集,再列出主文件」。先用 find_games(name="Skyrim") 取得 domainName,再调用 find_mods(game_domain="skyrimspecialedition", name="SkyUI")。

🧰 工具列表

工具 主要参数 用途
find_games 可选 name、sort、direction、offset、count 按名称片段查游戏,返回 ID 和 domainName。
find_mods 可选 game_domain、name、author、category、tag、adult_content 等 筛选或排序 Mod,取得 modId 和项目主页。
get_mod game_domain、mod_id 读取介绍、作者、上传者、封面、标签、统计和主页。v3.data.gallery_images 保留站点图集及各尺寸链接。
get_requirements game_domain、mod_id;可选 offset、reverse_offset 等 分别返回所需 Mod、所需 DLC 及依赖本项目的作品。用 include_disabled_legacy=true 查看已停用的旧声明。
get_file_requirements game_domain、mod_id、file_id 读取所选文件版本的依赖范围及 DLC 要求,需要相应账户权限。
list_files game_domain、mod_id;可选 category、offset、count 列版本、归档名和字节数,可按 MAIN、OPTIONAL 或 ARCHIVED 等类别筛选。
get_file game_domain、mod_id、file_id 读取文件的 GraphQL 元数据、网页地址和当前凭据可读取的 REST 详情。
get_download_links game_domain、mod_id、file_id;可选 nxm_url 申请指定文件的限时镜像地址。若需要网页授权,返回 filePage。
download_file game_domain、mod_id、file_id;可选 nxm_url 请求有效镜像并写入本地,返回绝对路径、实际字节数及校验结果。

分页与依赖。 搜索使用 offset、count 和 totalCount。get_requirements 的 nexusRequirements 是项目需要的 Mod,modsRequiringThisMod 是依赖它的作品;用 reverse_offset 独立翻后者的页。项目关闭旧依赖系统时,选择具体版本并使用 get_file_requirements。

下载授权。 有效的 API Key 可以读取更多文件资料。能否直接下载还取决于账户和具体文件。若返回 web_authorization_required,打开 filePage,按站点流程获取同一游戏、Mod 和文件的 nxm:// 链接,然后作为 nxm_url 传入。下载器保留同名文件;hashes.sha256 为本地计算值,实际核对过的上游摘要另列在 verifiedUpstreamHashes。

测试

uv run python -m unittest discover -s tests -v

用 SkyUI 进行实站验证时,在 PowerShell 中执行以下命令。下载获准时会写入临时目录,网页授权要求会单独报告。

$env:NEXUSMODS_LIVE_TEST = '1'
uv run --env-file .env python -m unittest discover -s tests -p test_live.py -v

构建与发布到 PyPI

首次发布前,在 PyPI 为 glossmod-nexusmods-mcp 登记 GitHub Trusted Publisher。仓库所有者填 GlossMod,仓库名填 nexusmods-mcp,工作流文件填 publish.yml,环境填 pypi。新项目可在 PyPI Publishing 预先登记。

在 GlossMod/nexusmods-mcp 的 GitHub Releases 页面为目标提交选择新标签,点击 Publish release。例如,v0.2.0 会发布 glossmod-nexusmods-mcp==0.2.0,v0.2.0rc1 会发布候选版。GitHub Actions 从标签取版本,构建并校验 wheel 和源码包,然后发布到 PyPI。可在本地运行 uv build 检查开发版本的构建产物。

参考:Nexus Mods GraphQL · REST v3 接口规范

Metadata

Release files for glossmod-nexusmods-mcp 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for glossmod-nexusmods-mcp 1.0.0
File Size Uploaded Provenance Actions
glossmod_nexusmods_mcp-1.0.0.tar.gz 64.6 kB With provenance Details for glossmod_nexusmods_mcp-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for glossmod-nexusmods-mcp 1.0.0
File Interpreter ABI Platform Actions
glossmod_nexusmods_mcp-1.0.0-py3-none-any.whl Python 3 none any Details for glossmod_nexusmods_mcp-1.0.0-py3-none-any.whl

Total release size: 77.9 kB

Release files / glossmod_nexusmods_mcp-1.0.0.tar.gz

Download URL glossmod_nexusmods_mcp-1.0.0.tar.gz
Size 64.6 kB
Tags Source
SHA-256 checksum
How to use checksums
14ce397bbfb9076c8c8ae24e9361e7be02218a6beafc9925b9e2768a3e4cbd72
BLAKE2b-256 checksum
How to use checksums
79ced6b0723c10e9f9e6d029f836744e993352d7d206f7c01a3c7e2506f6443c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / glossmod_nexusmods_mcp-1.0.0-py3-none-any.whl

Download URL glossmod_nexusmods_mcp-1.0.0-py3-none-any.whl
Size 13.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4672fc1e749219f4909ba7f47b5898003e9af4ad4e4e351dd937cc964e8debd0
BLAKE2b-256 checksum
How to use checksums
c19f42c34760da5c97cd5d0b9c8b15dd038c7ac6dbb3b1ddcbe6881845ad0679
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for glossmod-nexusmods-mcp 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for glossmod_nexusmods_mcp-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page