@bradford-tech/npm-package-readme-mcp-server

An MCP server that exposes npm registry data — package READMEs, metadata, and search — to MCP-compatible AI clients.

This is a maintained fork of naoto24kawa/npm-package-readme-mcp-server, republished under the @bradford-tech scope after the original was removed from GitHub and npm. No functional changes from the upstream 0.1.4 release.

Install

npm install -g @bradford-tech/npm-package-readme-mcp-server

Also works with pnpm add -g, yarn global add, or via npx (no install needed).

Configure your MCP client

Add the server to your client's MCP configuration:

{
  "mcpServers": {
    "npm-package-readme": {
      "command": "npm-package-readme-mcp-server"
    }
  }
}

Or run on demand with npx:

{
  "mcpServers": {
    "npm-package-readme": {
      "command": "npx",
      "args": ["-y", "@bradford-tech/npm-package-readme-mcp-server"]
    }
  }
}

Tools

The server exposes three tools to the connected client.

get_readme_from_npm

Fetches a package's README and extracts usage examples. Reads from the npm registry first, falls back to the linked GitHub repository.

| Parameter | Type | Default | Description | | ------------------ | ------- | ---------- | ---------------------------------------------------------- | | package_name | string | — | The npm package name (required). | | version | string | "latest" | Specific version or dist-tag. | | include_examples | boolean | true | Parse and return usage examples extracted from the README. |

Example call:

{ "package_name": "react", "version": "18.2.0" }

get_package_info_from_npm

Returns package metadata and download statistics for the latest version.

| Parameter | Type | Default | Description | | -------------------------- | ------- | ------- | -------------------------------- | | package_name | string | — | The npm package name (required). | | include_dependencies | boolean | true | Include runtime dependencies. | | include_dev_dependencies | boolean | false | Include dev dependencies. |

Example call:

{ "package_name": "express", "include_dependencies": true }

search_packages_from_npm

Searches the npm registry.

| Parameter | Type | Default | Description | | ------------ | ------ | ------- | ------------------------------ | | query | string | — | Search text (required). | | limit | number | 20 | Max results, 1–250. | | quality | number | — | Minimum quality score, 0–1. | | popularity | number | — | Minimum popularity score, 0–1. |

Example call:

{ "query": "testing framework", "limit": 10 }

How package data is fetched

• Package metadata and READMEs come from registry.npmjs.org.
• If the registry response has no README, the server resolves the repository field and fetches the README from the GitHub API.
• Download statistics come from api.npmjs.org/downloads.
• Responses are cached in memory (default TTL: 1 hour; search results: 10 minutes).

GitHub anonymous API requests are rate-limited to 60/hour. The server logs a warning when no token is available but still works for low-volume use.

Configuration

All settings are optional environment variables, passed via your MCP client's env field (or your shell, when launching directly).

| Variable | Default | Description | | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | | CACHE_TTL | 3600 | Default cache TTL in seconds for get_readme_from_npm and get_package_info_from_npm. Search results have a fixed 10-minute TTL. | | REQUEST_TIMEOUT | 30000 | Per-request timeout in milliseconds, applied to npm registry and GitHub API calls. | | GITHUB_TOKEN | — | GitHub personal access token. Raises the GitHub API rate limit from 60/hour to 5000/hour. | | LOG_LEVEL | INFO | One of ERROR, WARN, INFO, DEBUG (case-insensitive). Invalid values silently fall back to INFO. Logs are written to stderr. |

Example, with a GitHub token:

{
  "mcpServers": {
    "npm-package-readme": {
      "command": "npm-package-readme-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Requirements

• Node.js >= 20

Contributing

Issues and pull requests welcome at bradford-tech/npm-package-readme-mcp-server. See CONTRIBUTING.md for the developer setup.

License

MIT. See LICENSE.