NPM Advisor MCP server

An MCP (Model Context Protocol) server that exposes npm package intelligence to MCP-aware AI clients like Claude Code, Claude Desktop, Cursor, Continue, and any future MCP-aware editor or agent.

It's the same analysis pipeline that powers the NPM Advisor VSCode extension and the NPM Advisor Chrome extension: Fitness scoring, GitHub Security Advisories, license compatibility against your project's target license, bundle size, last-commit / stars, and replacement recommendations from e18e.

What it gives your AI

Five tools:

| Tool | What it returns | When the model calls it | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | get_package_stats | Full PackageStats for one package: Fitness score, security advisories, license + compatibility verdict, bundle size, GitHub stars + last commit, replacement recommendations. | "Tell me about lodash." "Is express maintained?" "Compare lodash and underscore." | | list_known_vscode_projects | Needs the NPM Advisor VSCode extension. Lists every workspace that extension has tracked (absolute path, parsed name, open/closed status, last-opened time), so a client with no project context (such as Claude Desktop) can resolve "my project". Returns empty when the extension is not installed. | "Which project should I look at?" "What do I have open in VSCode?" | | list_workspace_dependencies | Every package.json under a directory with its name and dep counts (no network). Auto-ascends from the server's working directory to the surrounding monorepo root. Maps a project before drilling in; works standalone, no VSCode extension needed. | "What does this project look like?" "Where do my dependencies live?" | | analyze_package_json | Per-dep stats for one package.json plus a roll-up summary (vulnerable / license-incompatible / replaceable counts). | "Audit this project." "Which dependencies should I worry about?" | | analyze_project | Analyzes one package (the single package.json at rootPath): publint publish-readiness, circular-dependency cycles, and e18e replacement opportunities for its declared deps, returned as one findings list tagged publint / circular-deps / replacements. The MCP equivalent of the VSCode extension's single-package "project analysis"; run it once per package to cover a monorepo. Read-only. | "Is my package.json ready to publish?" "Do I have any import cycles?" "Which of my deps have lighter alternatives?" |

Every tool returns plain JSON in the MCP text content slot so any AI client can parse it deterministically. The get_package_stats, analyze_package_json, and analyze_project tools include rendering hints in their descriptions that instruct Claude to present results as a rich visual artifact (metric cards, score bar chart, tabbed sections) when the client supports it.

Quick install

The server runs as a Node binary. The recommended invocation is via npx so you don't have to manage a global install or a path:

npx -y @agentic-web-labs/npm-advisor-mcp

It speaks MCP over stdio by default. Configure your AI client to spawn it as shown below, or jump to HTTP transport to run it as a long-lived local or remote server instead.

The examples throughout this README include an optional GITHUB_TOKEN. It is not required (the server runs fine without it), but a public-read token raises the GitHub API rate limit from 60 to 5,000 requests per hour, which the analysis relies on for advisories, stars, and last-commit data. Omit it to stay unauthenticated, or see GitHub authentication for the details and required scopes.

Claude Code

Add the server via the Claude Code CLI from your project root:

claude mcp add npm-advisor --env GITHUB_TOKEN=ghp_… -- npx -y @agentic-web-labs/npm-advisor-mcp

This writes an entry to ~/.claude.json (or .mcp.json if you want it scoped to the project). Restart any open Claude Code session and ask: "List my dependencies and tell me which ones have security issues."

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "npm-advisor": {
      "command": "npx",
      "args": ["-y", "@agentic-web-labs/npm-advisor-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_…"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under the connector icon in the chat composer.

Cursor

In Cursor's settings, open MCP → Add new global MCP server and paste:

{
  "mcpServers": {
    "npm-advisor": {
      "command": "npx",
      "args": ["-y", "@agentic-web-labs/npm-advisor-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_…"
      }
    }
  }
}

Cursor's Composer can now call the tools. Toggle them on under MCP Tools when you start a chat.

VSCode (built-in MCP support, 1.96+)

Add to your workspace's .vscode/mcp.json (or user-scope mcp.json):

{
  "servers": {
    "npm-advisor": {
      "command": "npx",
      "args": ["-y", "@agentic-web-labs/npm-advisor-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_…"
      }
    }
  }
}

Copilot Chat in agent mode will discover the tools.

Continue

In ~/.continue/config.json (or the project-scoped .continue/config.json):

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@agentic-web-labs/npm-advisor-mcp"],
          "env": {
            "GITHUB_TOKEN": "ghp_…"
          }
        }
      }
    ]
  }
}

HTTP transport (host it on localhost or a remote server)

By default the binary speaks MCP over stdio so AI clients can spawn it as a subprocess. Pass --http to instead start a Streamable HTTP server. This is useful when you want one running instance shared between several clients on your machine, or when you want to host npm-advisor on a remote server and connect to it over the network.

Run locally

GITHUB_TOKEN=ghp_… npx -y @agentic-web-labs/npm-advisor-mcp --http

This binds to 127.0.0.1:3845 (loopback only, not reachable from other machines) and serves MCP at http://127.0.0.1:3845/mcp.

Override the port and host with flags:

npx -y @agentic-web-labs/npm-advisor-mcp --http --port 4000 --host 127.0.0.1

Point any MCP-aware client at the URL. For example, Claude Desktop:

{
  "mcpServers": {
    "npm-advisor": {
      "transport": "http",
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}

In HTTP mode the optional GITHUB_TOKEN is set where the server is launched (shown above), not in the client config, since the client only connects to the URL.

Host it remotely

To accept connections from other machines, bind to a non-loopback address (0.0.0.0 for all interfaces, or a specific interface IP):

GITHUB_TOKEN=ghp_… MCP_HTTP_TOKEN=your-long-random-token \
  npx -y @agentic-web-labs/npm-advisor-mcp --http --host 0.0.0.0 --port 3845

When MCP_HTTP_TOKEN is set, every request must include:

Authorization: Bearer your-long-random-token

The server prints a warning to stderr if you bind to a non-loopback address without a token. Public deployments should also sit behind a reverse proxy that terminates TLS (https://); the server itself only speaks plain HTTP.

A typical Claude Desktop entry pointing at a hosted instance:

{
  "mcpServers": {
    "npm-advisor": {
      "transport": "http",
      "url": "https://npm-advisor.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-long-random-token"
      }
    }
  }
}

CLI flags

| Flag | Default | Description | | ------------------------- | ----------------- | -------------------------------------------------------- | | --http | (off, stdio mode) | Switch to the Streamable HTTP transport. | | --port <n> | 3845 | TCP port to listen on. | | --host <addr> | 127.0.0.1 | Bind address. Use 0.0.0.0 to expose on all interfaces. | | --transport stdio\|http | stdio | Long form of --http / --stdio. |

--port, --host, and --transport also accept the --name=value form.

GitHub authentication (optional but recommended)

Without a token GitHub rate-limits the server's API calls to 60 requests / hour / IP, which is easy to exhaust during a workspace audit. Set a personal-access token in the environment your AI client launches the server in:

export GITHUB_TOKEN=ghp_…

Or GH_TOKEN, which is also recognized. With a token the rate limit jumps to 5,000 requests / hour.

Create a token

1. Open github.com/settings/tokens and choose Generate new token → Generate new token (classic).
2. Give it a name (for example npm-advisor-mcp) and an expiration.
3. Leave every scope unchecked. The server reads only public data and never touches private repositories, so no scopes are required (the token still raises the rate limit).
4. Click Generate token and copy the ghp_… value. GitHub shows it only once.
5. Set it as GITHUB_TOKEN (or GH_TOKEN) in your MCP client's env block using one of the configs above, or export it in the shell that launches the server.

Prefer a fine-grained token? Create one with read-only Public Repositories access and no account permissions.

A typical Claude Desktop entry with auth:

{
  "mcpServers": {
    "npm-advisor": {
      "command": "npx",
      "args": ["-y", "@agentic-web-labs/npm-advisor-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_…"
      }
    }
  }
}

A ready-to-copy template lives at .env.example in the source repo. Copy the keys you need into your MCP client's env block, or source the file before running the binary directly.

On startup the server prints one line to stderr indicating whether a token was detected, so you can confirm your client actually forwarded the env var:

npm-advisor-mcp: GitHub auth = token (from $GITHUB_TOKEN); rate limit 5,000 req/hr

or, when no token was passed:

npm-advisor-mcp: GitHub auth = unauthenticated; rate limit 60 req/hr (set $GITHUB_TOKEN to lift)

How it works

                ┌──────────────────────────────────────┐
                │  Claude Desktop / Code / Cursor /    │
                │  Continue / VSCode (MCP-aware AI)    │
                └─────────────────┬────────────────────┘
                                  │ JSON-RPC over stdio
                                  │   or Streamable HTTP (--http)
                                  ▼
            ┌───────────────────────────────────────────┐
            │  npm-advisor-mcp (this package)           │
            │   ┌─────────────────────────────────────┐ │
            │   │ McpServer (modelcontextprotocol)    │ │
            │   │   tools:                            │ │
            │   │   • get_package_stats               │ │
            │   │   • list_known_vscode_projects      │ │
            │   │   • list_workspace_dependencies     │ │
            │   │   • analyze_package_json            │ │
            │   │   • analyze_project                 │ │
            │   └─────────────────────────────────────┘ │
            │   ┌─────────────────────────────────────┐ │
            │   │ Analysis engine (bundled)           │ │
            │   │   data sources:                     │ │
            │   │   - npm registry                    │ │
            │   │   - GitHub GraphQL (advisories,     │ │
            │   │     stars, last commit)             │ │
            │   │   - Bundlephobia (size)             │ │
            │   │   - OSADL license matrix            │ │
            │   │   - e18e replacement rules          │ │
            │   │   - calculateScore (Fitness)        │ │
            │   └─────────────────────────────────────┘ │
            └───────────────────────────────────────────┘

The AI client either spawns this process as a subprocess (stdio mode, default) or connects to a long-running HTTP instance (Streamable HTTP mode, --http). Either way, tools register on startup, the client lists them, and the model invokes any tool at any time. Every tool result flows back as JSON the model can quote, summarize, or act on.

Privacy

All API calls go to public endpoints: registry.npmjs.org, bundlephobia.com, api.github.com, and the OSADL license matrix bundled into the server. This server doesn't phone home anywhere else, and reads only files under the workspace path you ask list_workspace_dependencies, analyze_package_json, or analyze_project to scan.

Build from source

The package lives in the agentic-web-labs monorepo. To build it yourself:

git clone https://github.com/amedina/agentic-web-labs.git
cd agentic-web-labs
pnpm install
pnpm build:npm-advisor-mcp

This produces packages/mcp/npm-advisor-mcp/dist/server.js with a shebang and the executable bit set, so you can also point your AI client straight at it during development:

{
  "mcpServers": {
    "npm-advisor-dev": {
      "command": "node",
      "args": ["/absolute/path/to/dist/server.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_…"
      }
    }
  }
}

To run the built server directly from the repo root for local testing (for example, against the MCP Inspector):

# stdio mode
pnpm start:npm-advisor-mcp

# Streamable HTTP mode on http://127.0.0.1:3845/mcp
pnpm start:npm-advisor-mcp:http

License

Apache-2.0

Related packages

• NPM Advisor Chrome extension
• NPM Advisor VSCode extension, which also exposes these tools through @npm-advisor in Copilot Chat