mcpField
N
npm Registry MCP Server

npm Registry MCP Server

ローカル
yaw.sh開発ツール22 週間前に更新

npm Registry MCP Server について

npm Registry MCP Serverは、コーディングエージェントやMCPクライアントからnpmレジストリの検索、監査、依存関係分析、管理操作を行うためのサーバーです。読み取りから書き込み、組織管理までを扱い、書き込みには安全策と認証処理を備えています。

主な機能

  1. 01パッケージ、ダウンロード数、依存関係を検索
  2. 02セキュリティ問題とライセンスを確認
  3. 03非推奨設定、dist-tag、所有者を管理
  4. 04組織、チーム、アクセスを操作
  5. 05書き込みツールに安全策と注釈を付与
  6. 06APIトークンなしで読み取り

活用シーン

  1. 01npmパッケージのメンテナーとバージョンを調査
  2. 02既知の脆弱性について依存関係を監査
  3. 03パッケージの非推奨情報やdist-tagを変更
  4. 04組織、チーム、パッケージのアクセス権を確認

MCP 対応

このMCPサーバーは、npmレジストリ操作をMCPクライアントに公開します。読み取りは匿名で利用でき、書き込みや一部の管理操作はNPM_TOKENで認証できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"yawlabs-npmjs": {
"command": "npx",
"args": [
"-y",
"@yawlabs/npmjs-mcp"
]
}
}
}
起動コマンドnpx -y @yawlabs/npmjs-mcp

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@yawlabs/npmjs-mcp0.17.0

ツール

64

掲載時のツール一覧 · 2 週間前に更新

パラメーター型必須説明
fromnumberいいえページネーションのオフセット
sizenumberいいえ結果数(デフォルト:20、最大:250)
querystringはい検索テキスト。次の修飾子をサポートします:keywords:x、author:x、maintainer:x、scope:x
qualitynumberいいえ品質スコアの重み(0-1)
popularitynumberいいえ人気度スコアの重み(0-1)
maintenancenumberいいえメンテナンススコアの重み(0-1)

詳細

@yawlabs/npmjs-mcp

Add to Yaw MCP

ワンクリックでローカルの Yaw MCP 設定に追加され、すべての Yaw Terminal セッションで利用できるようになります。または、以下の手順で手動インストールしてください。

npm version License: MIT GitHub stars

Claude Code、Cursor、あらゆる MCP クライアントから npm レジストリの操作を実行できます。 レジストリ全体をカバーする64個のツールを備え、パッケージ情報、セキュリティ監査、依存関係の分析、組織・チームの管理、通常はローカルで手間のかかる書き込み操作(npm deprecate、npm dist-tag、npm owner、npm unpublish)に対応します。

Yaw Labsが開発・メンテナンスしています。

このサーバーを選ぶ理由

ほかの npm MCP サーバーはnpm searchをラップして、それで終わりです。このサーバーは違います。

  • レジストリの HTTP API を全面的にカバー — 読み取り、書き込み、組織、チーム、フック、プロベナンス、信頼されたパブリッシャー、運用状況の健全性にわたる64個のツールを備えています。npm viewだけではありません。
  • エージェントで実際に動作する書き込み操作 — npm_deprecate、npm_undeprecate、npm_dist_tag_set、npm_unpublish_versionは、2FA バイパスが有効な Granular Access Token を使って HTTP API を直接呼び出します。2FA プロンプトや--otp探しは不要で、セッションに紐づく.npmrcが原因のENEEDAUTHも発生しません。(2026-07-31以降、npm では、2FA バイパスが有効な場合でも、所有者、アクセス権、チームのメンバーシップと権限付与、組織のメンバーシップとトークンの変更に対して、対話型の2FA チャレンジが必要です。これらのツールでは、人が実行する正確なnpmコマンドをエラーに示します。)
  • エージェントを考慮したエラー通知 — npm_check_authとnpm_publish_preflightは非対話型のコンテキストを検出し、人が実行できるコマンドを返します。また、すべての書き込みエラーで、送信した内容と npm CLI での同等のコマンドを示すため、復旧不能なエラーを繰り返し試すことはありません。
  • デフォルトで安全 — npm_unpublish_*にはconfirm: trueが必要です。npm_owner_removeは、自分自身を締め出す操作を防ぎます。npm_deprecateは、レジストリの1024文字制限を超えるメッセージを送信前に拒否します。
  • 運用手順を組み込み済み — npm_ops_playbookは、ツール、CLI、CI のどれを使うかを判断する標準的な決定マトリクスを返すため、エージェントは最初から適切な方法を選べます。
  • ツールのアノテーション — すべてのツールでreadOnlyHint、destructiveHint、idempotentHint、openWorldHintを宣言しているため、MCP クライアントは安全な操作の確認を省略できます。
  • 読み取りには API キー不要 — 検索、パッケージ、ダウンロード、セキュリティ、依存関係ツリー、ライセンスは、すべて匿名で利用できます。認証はNPM_TOKENで任意に有効化できます。
  • 即時起動 — ランタイム依存関係なしの単一バンドルファイルとして提供されます。node_modulesのインストールに5分かかることはありません。
  • 入力の堅牢化 — パッケージ名、スコープ、バージョン、dist-tag、チーム名を、npm の実際の制約に照らして正規表現で検証します。URL の構築時における CRLF インジェクションやパストラバーサルを防ぎます。

クイックスタート

1. プロジェクトのルートに .mcp.json を作成します

macOS/Linux/WSL:

{
  "mcpServers": {
    "npm": {
      "command": "npx",
      "args": ["-y", "@yawlabs/npmjs-mcp@latest"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "npm": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/npmjs-mcp@latest"]
    }
  }
}

Windows ではなぜ追加の手順が必要ですか? Node 20 以降、child_process.spawn では .cmd ファイル(Windows での npx はこれに該当します)を直接実行できません。cmd /c でラップするのが標準的な回避方法です。

2. 再起動して承認します

Claude Code(または MCP クライアント)を再起動し、プロンプトが表示されたら npm MCP サーバーを承認します。

3.(任意)書き込み操作用に npm トークンを追加します

読み取り専用ツールは、設定なしで動作します。書き込みツール(deprecate、dist-tag、owner、team_*、org_member_*、unpublish、hook_*、access_set*、token_revoke)を使うには、env ブロックに NPM_TOKEN を追加します。

{
  "mcpServers": {
    "npm": {
      "command": "npx",
      "args": ["-y", "@yawlabs/npmjs-mcp@latest"],
      "env": {
        "NPM_TOKEN": "npm_xxxxxxxxxxxx"
      }
    }
  }
}

エージェントに管理させたいパッケージと組織だけを対象に設定したきめ細かなアクセストークンを使用してください。

これで完了です。AI アシスタントに次のように尋ねてみましょう。

「my-old-pkg 1.x を v2 への案内付きで非推奨にして」

「fastify の依存関係ツリーを 3 階層まで見ると、どんな感じ?」

「express に既知の CVE がないか監査して、修正方法を教えて」

「next.js のメンテナーは誰で、それぞれが最後に公開したのはいつ?」

設定

環境変数デフォルト説明
NPM_TOKEN(なし)npm アクセストークンです。書き込み/認証/組織/アクセス/フックのツールでのみ必要です。Granular Access Token(ヘッドレスでの書き込みには 2FA バイパス付き)を使用してください。Automation トークンを含むクラシックトークンは、2025 年 12 月に失効しました。
NPM_REGISTRYhttps://registry.npmjs.org別のレジストリ(エンタープライズ/プライベート)です。npm HTTP API と同じ形式に対応している必要があります。
NPM_REQUEST_TIMEOUT_MS30000レジストリリクエストの各試行に適用されるタイムアウト(ミリ秒)です。レスポンス本文の読み取り時間も含みます。読み取りでは、タイムアウト、ネットワークエラー、または HTTP 429/502/503/504 が発生すると、合計で最大 3 回まで再試行します。そのため、読み取りが停止した場合、この値の約 3 倍の時間がかかることがあります。書き込みでは、レジストリ側ですでに適用済みの可能性があるため、タイムアウトまたはネットワークエラーの後に再送信することはありません。429/503 の場合にのみ再試行します。正の有限数でない値(Infinity を含む)を指定するとデフォルトに戻るため、タイムアウトを無効にはできません。
NPM_RETRY_BACKOFF_MS500再試行までの基本待機時間です。デフォルトでは再試行ごとに倍になり、500 ms、次に 1000 ms となります。再試行対象のレスポンスに Retry-After ヘッダーが含まれている場合は、この値の設定にかかわらず、その待機時間(最大 30 秒)が使われます。0、空の値、または空白のみの値を指定すると、バックオフ待機はなくなります。それ以外の負の値または数値以外の値を指定すると、デフォルトに戻ります。
DEBUG(なし)すべての npm API 呼び出しの各試行について、1 行ずつ stderr にログを出力します。ログには [npmjs-mcp] のプレフィックスが付き、メソッド、URL、続いてステータスとレスポンスヘッダー受信までのミリ秒数、または再試行までの待機時間と試行回数、またはネットワークエラーが記録されます。トークンがログに出力されることはありません。値が正確に npmjs-mcp または * の場合にのみ有効になります。1 や npmjs-mcp:* など、その他の値は無視されます。他のツール用に設定された DEBUG=* でも有効になります。
NPMJS_MCP_RUNTIMEautoauto:ランチャーがすでに実行されている oam が 0.18.0 以降であれば、その oam 上で実行します。それ以外の場合は、見つかった中で最も新しい 0.18.0 以降の oam バイナリ(OAM_BIN を参照)で実行します。それも見つからない場合は Node で実行します。0.18.0 より古い oam ホストがサーバーを直接実行することはありません。代わりに、使用可能な中で最も新しい oam に処理を引き継ぐか、PATH 上の Node に引き継ぐか、どちらもない場合はエラーで終了します。使用できない OAM_BIN は必ず stderr に表示されます。見つかったその他の oam バイナリは、そのどれも使用できない場合に限り、理由とともに表示されます。新しいバイナリに置き換えられた古いコピーについては何も表示されません。oam:同じ動作ですが、Node にフォールバックする代わりにエラーで終了します。node:常に Node を使用します。npx の場合はプロセス内で実行し、クライアントが oam run でコマンドを起動した場合は PATH 上の Node に処理を引き継ぎます。大文字と小文字は区別されません。それ以外の値は auto と同じ動作になります。
NPMJS_MCP_SANDBOX(なし)1 を指定すると、新しく起動した oam(0.18.0 以降)で --permission を指定してサーバーを実行します。許可されるのは npm レジストリのホスト(および NPM_REGISTRY のホスト)と、サーバーが読み取る環境変数のみです。ファイルシステムとサブプロセスへのアクセスは引き続き拒否されます。すでに oam 上で実行中の場合でも、新たに起動します。auto の場合、使用可能な oam が見つからないとき、または見つかった oam の起動に失敗したときは、サンドボックスなしでサーバーが実行され、その旨が stderr に表示されます。これを致命的なエラーにするには、NPMJS_MCP_RUNTIME=oam と組み合わせてください。NPMJS_MCP_RUNTIME=node の場合は無視されます。
OAM_BIN(なし)検出より優先して使用する oam バイナリのパスです。0.18.0 以降である必要があります。存在しない場合、古いバージョンの場合、または実行できない場合は、ランチャーがその旨を stderr に表示して、検出を続行します。検出では、OAM_INSTALL_DIR が設定されている場合はその場所を調べ、次にインストール先(Windows では %LOCALAPPDATA%\oam\bin、続いて ~/.oam/bin、それ以外では ~/.oam/bin)、その後 PATH を調べます。見つかったすべての oam にバージョンを問い合わせ、最も新しいものを使用します。同じバージョンの場合は、先に見つかった場所が優先されます。Windows では oam.exe のみが対象です。oam.cmd/oam.bat のシムは実行されず、使用可能な oam が見つからない場合は stderr に表示されます。NPMJS_MCP_RUNTIME=node の場合、およびサンドボックスなしで oam 0.18.0 以降上ですでに実行されている場合は無視されます。
ランタイム

このサーバーには、oam ランタイムを優先し、利用できない場合は Node にフォールバックするランチャーが付属しています。サーバー本体は node: 組み込みモジュールのみを使用する、事前バンドル済みの ESM ファイルです。そのため、どちらの方法でも動作は同じです。ハンドシェイク、64 個すべてのツール、レジストリへのライブ呼び出しを含む、MCP の全機能で検証済みです。

最新リリースの oam 0.18.0 が最低要件です。 ランチャーは、見つかったすべての oam バイナリにバージョンを問い合わせ、要件を満たすもののうち最も新しいバージョンを実行します。古い oam でサーバーを実行することはなく、該当するものがなければ Node にフォールバックします(NPMJS_MCP_RUNTIME=oam を設定すると、フォールバックせずにエラーになります)。詳細は設定を参照してください。

フォールバックによる追加コストはありません。npm はランチャーを実行するためにすでに Node を起動しているため、フォールバックはプロセス内での import() で実行されます。追加のプロセス起動も、起動時間の増加もありません。

oam は高速ですが、ランチャーは高速ではありません。 windows-arm64 で測定した、n=12 の中央値です。プロセス起動から最初の MCP initialize 応答までの時間を示します。

起動方法時間node との比較
oam run dist/index.js116 ms0.67x
node dist/index.js172 ms1.00x
このランチャー(node が oam を起動)243 ms1.41x

npm の bin エントリーは Node スクリプトなので、そこから oam を起動すると、Node の起動時間に oam の起動時間が加わります。oam で短縮できる時間よりも長くなります。このランチャーは、npx ユーザーが自動的に oam を使えるようにするためのものであり、高速な実行方法ではありません。

oam の速度を活かしたい場合は、MCP ホストから oam を直接指定してランチャーをスキップしてください。

{ "mcpServers": { "npmjs": { "command": "oam", "args": ["run", "/abs/path/to/dist/index.js"] } } }

ベンチマークに関する注意:cargo の target/ ディレクトリにある oam ではなく、インストール済みの oam(~/.oam/bin)を測定してください。並行して実行中の cargo build が測定中にバイナリを置き換えることがあり、生成されたばかりのバイナリは、比較対象のウォーム状態の node.exe とは異なり、キャッシュが効いていないためです。oam はプレアルファ版です。ご自身のハードウェアで再測定してください。

oam の --permission サンドボックスはオプトインです。 NPMJS_MCP_SANDBOX=1 を設定すると、ランチャーは oam(0.18.0 以降)上でサーバーを起動し、以下の設定を適用します。

  • ネットワーク:registry.npmjs.org:443、api.npmjs.org:443、replicate.npmjs.com:443 へのアクセスを許可します。また、NPM_REGISTRY が設定されている場合は、そのホストとポートへのアクセスも許可します(指定されたポート、または https の場合は 443、http の場合は 80)。oam は各リクエストを host:port の完全一致で照合するため、各許可設定の対象はサーバーが使用する単一のポートに限定されます。
  • 環境変数:サーバーが読み取る次の変数のみを許可します:NPM_TOKEN、NPM_REGISTRY、NPM_REQUEST_TIMEOUT_MS、NPM_RETRY_BACKOFF_MS、DEBUG。
  • ファイルシステムとサブプロセス:アクセスを全面的に拒否します。サーバーは実行時にファイルを読み込まず、サブプロセスも起動しません。そのため、これらを突然必要とする依存関係は信頼されず、ランタイムによって停止されます。これは、NPM_TOKEN を保持するプロセスにとって重要です。

デフォルトの NPMJS_MCP_RUNTIME=auto では、利用可能な oam が見つからない場合、または選択された oam の起動に失敗した場合、サーバーはサンドボックスなしで実行され、その旨が stderr に出力されます。NPMJS_MCP_RUNTIME=oam も設定すると、その状況はエラーになります。

デフォルトで有効になっていないのは、許可設定が不完全でも明示的なエラーにならず、気づかないまま失敗するためです。registry.npmjs.org のみを許可した oam 0.9.0 で測定したところ、npm_health は HTTP 200 を返し、weeklyDownloads: null となりましたが、エラーはありませんでした。ダウンロード数は api.npmjs.org から取得されるためです。環境変数が許可されていない場合は、さらに問題です。oam は許可されていない環境変数を例外を発生させずに process.env から取り除くため、拒否された NPM_TOKEN はトークンが存在しない場合と同じように見え、「拒否」ではなく「未認証」となります。

その他の MCP クライアント:

クライアント設定ファイル
Claude Code.mcp.json(プロジェクトルート)または ~/.claude.json(グローバル)
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json(macOS)
Cursor~/.cursor/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
VS Code.vscode/mcp.json

上記と同じ JSON ブロックを、これらのいずれかで使用してください。

ツール(64 個)

検索(1 個)
  • npm_search — キーワード、作成者、スコープなどの修飾子を使って npm レジストリを検索します。
パッケージ(6)
  • npm_package — メタデータ:説明、dist-tag、メンテナー、ライセンス、リポジトリ。
  • npm_version — 特定のバージョンの詳細なメタデータ。
  • npm_versions — 公開済みのすべてのバージョンと日付。
  • npm_readme — README の内容。
  • npm_dist_tags — dist-tag(latest、next、beta など)。
  • npm_types — TypeScript の型サポート(組み込み型または @types/*)。
依存関係(3)
  • npm_dependencies — 依存関係の一覧(prod、dev、peer、optional)。
  • npm_dep_tree — 推移的依存関係のツリー(深さを設定可能)。
  • npm_license_check — パッケージと直接依存関係のライセンス監査。
ダウンロード(4)
  • npm_downloads — 期間内の合計ダウンロード数。
  • npm_downloads_range — 日別のダウンロード数。
  • npm_downloads_bulk — 最大 128 個のパッケージのダウンロード数を比較。
  • npm_version_downloads — バージョンごとのダウンロード数。
セキュリティ(3)
  • npm_audit — パッケージに既知の脆弱性がないか確認。
  • npm_audit_deep — CVSS スコア、CWE、修正の推奨事項を含む完全な監査。
  • npm_signing_keys — レジストリの ECDSA 署名鍵。
分析(4)
  • npm_compare — 2~5 個のパッケージを並べて比較。
  • npm_health — メンテナンス状況、ダウンロード数、セキュリティ、非推奨化の概要。
  • npm_maintainers — メンテナーと公開履歴。
  • npm_release_frequency — リリースの頻度と間隔。
レジストリ(3)
  • npm_registry_stats — npm 全体の合計ダウンロード数。
  • npm_recent_changes — CouchDB の changes フィードから最近公開されたパッケージを取得。
  • npm_ops_playbook — npm の操作に関する標準的な手順。使用するツールがわからない場合は、まずこれを呼び出してください。
来歴と信頼性(2)
  • npm_provenance — Sigstore 証明(SLSA、公開)。
  • npm_trusted_publishers — CI/CD プロバイダーとの OIDC 信頼関係。
認証(5、NPM_TOKEN が必要)
  • npm_whoami — 認証済みユーザー。
  • npm_profile — プロフィール、メールアドレス、2FA の状態。
  • npm_tokens — アクセストークンの一覧。
  • npm_verify_token — 1 回の呼び出しで権限を確認。書き込みに失敗した際のデバッグでは、まずこれを呼び出してください。
  • npm_user_packages — ユーザーが公開したパッケージ。
アクセスと組織(7、NPM_TOKEN が必要)
  • npm_collaborators — パッケージのコラボレーターと権限。
  • npm_package_access — パッケージのアクセス設定。
  • npm_org_members — 組織のメンバーと役割。
  • npm_org_packages — 組織のパッケージ。
  • npm_org_teams — 組織のチーム。
  • npm_team_packages — チームのパッケージ権限。
  • npm_team_members — チームのメンバーと役割。
ワークフロー(2)
  • npm_check_auth — ヘッドレス環境での公開可否を含む認証の健全性チェック。
  • npm_publish_preflight — 公開前の検証チェックリスト。
書き込み操作(19、書き込みスコープ付きの NPM_TOKEN が必要)

これらは、npm deprecate などがローカル環境で失敗する原因となる CLI/2FA の手間を回避します。すべて NPM_TOKEN を使用した HTTP API で実行されます。

  • npm_deprecate — パッケージまたは特定のバージョンを非推奨にします(レジストリのメッセージ上限 1024 文字を適用します。メッセージの句読点に制限はありません)。
  • npm_undeprecate — 非推奨設定を解除します。
  • npm_unpublish_version — バージョンを公開解除します。confirm: true が必要です。
  • npm_unpublish_package — パッケージ全体を公開解除します。confirm: true が必要です。
  • npm_dist_tag_set — dist-tag の参照先をバージョンに設定します。
  • npm_dist_tag_remove — dist-tag を削除します(latest は拒否されます)。
  • npm_owner_add — メンテナーを追加します(/-/user/ でユーザーを検索)。
  • npm_owner_remove — メンテナーを削除します(自分自身がロックアウトされる操作は防止されます)。
  • npm_access_set — アクセス設定を public/private/restricted に設定します。
  • npm_access_set_mfa — 2FA の要件を設定します(none/publish/automation)。
  • npm_team_grant / npm_team_revoke — パッケージに対するチームの権限を付与/取り消します。
  • npm_team_create / npm_team_delete — 組織内にチームを作成/削除します。
  • npm_team_member_add / npm_team_member_remove — チームメンバーを管理します。
  • npm_org_member_set / npm_org_member_remove — 組織のメンバーシップと役割を管理します。
  • npm_token_revoke — キーを指定してアクセストークンを取り消します。
Webhook(5 件、NPM_TOKEN が必要)
  • npm_hook_add — パッケージ、スコープ、またはユーザーに Webhook を登録します。
  • npm_hook_list — Webhook を一覧表示します(パッケージでの絞り込みは任意)。
  • npm_hook_get — 単一の Webhook を取得します。
  • npm_hook_update — エンドポイント/シークレットを更新します。
  • npm_hook_remove — Webhook を削除します。

操作の選択マトリックス

操作推奨される方法理由
読み取り(検索/表示/統計)これらの MCP ツール、認証不要高速で、手間がかかりません
非推奨化/dist-tag/公開取り消しnpm_deprecate、npm_dist_tag_* などHTTP API を使用するため、2FA バイパス対応トークンがあれば CLI の 2FA による手間がありません
所有者/アクセス/チーム/組織/トークンの変更npm_owner_*、npm_access_set*、npm_team_*、npm_org_member_*、npm_token_revoke2026-07-31 以降、対話型の 2FA チャレンジが必要です。401/403 の場合、エラーに人間が実行する npm コマンドが記載されます
公開ワークステーションから bash release.sh X.Y.Z を実行しますこのリポジトリには CI リリースワークフローがありません(b2c256c で削除されました)。注:ワークステーションからの公開には sigstore の来歴が付与されません。--provenance には CI OIDC が必要です。
公開取り消しnpm_unpublish_version(confirm: true を指定)CLI より安全です。72 時間以内は取り消せません
CLI による代替手段エラーに記載された npm コマンドを、ワンタイムパスワードのプロンプトに応答できる人間が実行します対話型 2FA が必要な変更で 401/403 が返された場合、またはメッセージにコマンド名が記載された 422 が返された場合

セッションの開始時に npm_ops_playbook を呼び出し、最新のマトリックスを取得してください。

使用例

依存関係を監査する
> "What vulnerabilities does lodash 4.17.20 have and what's the fix?"
→ npm_audit_deep({
    name: "my-project",              // the PROJECT being audited, not the dependency
    version: "1.0.0",
    dependencies: { lodash: "4.17.20" }   // required — the set to audit
  })

複数のパッケージをまとめて手早く確認するには、npm_audit に名前とバージョンのマップを直接渡します:npm_audit({ packages: { lodash: ["4.17.20"] } })。

パッケージを非推奨にする
> "Deprecate @myorg/legacy-sdk with a pointer to @myorg/sdk"
→ npm_deprecate({ name: "@myorg/legacy-sdk", message: "Renamed to @myorg/sdk — install that instead" })
パッケージの健全性を比較する
> "Compare fastify vs express vs koa for maintenance health"
→ npm_compare({ packages: ["fastify", "express", "koa"] })
→ npm_health({ name: "fastify" }) // ...etc
dist-tag を切り替える
> "Point @myorg/pkg@latest at 3.2.1"
→ npm_dist_tag_set({ name: "@myorg/pkg", tag: "latest", version: "3.2.1" })
書き込みの失敗をデバッグする
> "My deprecate keeps returning 401 — what's wrong?"
→ npm_verify_token()  // Confirms token scope, packages, 2FA state
→ npm_ops_playbook()  // Returns the canonical retry sequence

トラブルシューティング

「Error: NPM_TOKEN is required」

  • 呼び出したツールには認証が必要です。MCP 設定の env ブロックに NPM_TOKEN を追加し、クライアントを再起動してください。
  • 操作対象にしたいパッケージと組織だけを対象にしたきめ細かなアクセストークンを使用することをおすすめします。

「HTTP 401 Unauthorized」または「HTTP 403 Forbidden」

  • トークンには対象パッケージのスコープがありません。npm_verify_token を呼び出すと、トークンで実際に書き込み可能なパッケージと組織が報告されます。
  • OTP チャレンジは 401 として返され、2FA ポリシーによる拒否は 403 として返されます。いずれも 422 にはなりません。非推奨化、非推奨解除、dist-tag、公開取り消しについては、2FA バイパスを有効にしたきめ細かなアクセストークンで、どちらの問題も解決できます。Automation トークンを含む Classic トークンは、2025 年 12 月に失効しました。
  • 所有者、アクセス、チームのメンバーシップと権限付与、組織のメンバーシップ、トークンの変更には、2FA バイパス対応トークンであっても、2026-07-31 以降は対話型の 2FA チャレンジが必要です。これらを解決できるトークンはありません。エラーには、人間が実行してワンタイムパスワードのプロンプトに応答する必要がある正確な npm コマンドが記載されます。

書き込み時の「HTTP 422 Unprocessable」

  • まず末尾の Raw: 本文を確認してください。レジストリが返した実際の理由が記載されています。それより前のメッセージには、その呼び出しで送信された内容と、違反した可能性のある npm の文書化されたルールが記載され、その後に(該当するものがあれば)npm CLI の同等コマンドが示されます。このコマンドはレジストリの完全なエラーを表示し、必要に応じてワンタイムパスワードを求めます。
  • npm_deprecate では、公開済みのバージョンに一致しない versionRange と 1024 文字を超えるメッセージは、書き込み前に HTTP 400 としてローカルで拒否されるため、どちらも 422 の原因にはなりません。範囲のエラーには公開済みのバージョンが列挙されます。その一覧、または npm_versions を使って範囲を修正してください。
  • メッセージの句読点は原因ではありません。末尾のピリオドを em ダッシュに置き換えても 422 は解消されません。

Windows:MCP サーバーが起動しない

  • クイックスタートの cmd /c npx ... パターンを使用してください。Node 20 以降では .cmd ファイルを直接起動できません。

要件

  • Node.js 20.11 以降(package.json では engines.node: ">=20.11.0" と宣言されています)
  • (任意)書き込み操作用の npm アクセストークン

コントリビューション

git clone https://github.com/YawLabs/npmjs-mcp.git
cd npmjs-mcp
npm install
npm run lint       # Biome check
npm run lint:fix   # Auto-fix
npm run build      # tsc + esbuild bundle
npm test           # node --test

リリースプロセスを含むワークフローの詳細については、CONTRIBUTING.mdをご覧ください。

ライセンス

MIT

Xで@YawLabsをフォロー

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。