What can you do with this server?

This server provides an MCP interface to the npm registry, offering the following tools: * get_readme_from_npm: Fetches a package's README (with GitHub fallback) and optionally extracts usage examples. Supports specific versions and dist-tags. * get_package_info_from_npm: Returns detailed metadata, version info, download statistics, and optionally runtime and/or dev dependencies for a package. * search_packages_from_npm: Searches the npm registry by keyword/query, with control over result count (1–250) and optional filtering by minimum quality and popularity scores. Additionally, you can configure a GitHub personal access token to improve API rate limits when fetching READMEs from GitHub, and customize caching TTL and per-request timeouts.

Which integrations are available for this server?

Fetches npm package READMEs, metadata, and search results from the npm registry. Provides tools for retrieving package readmes, package info, and searching for packages.

How do I use @bradford-tech/npm-package-readme-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@bradford-tech/npm-package-readme-mcp-server show me the readme for lodash" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

by bradford-tech

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

@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).

Related MCP server: npm-docs-server

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.

Available Tools

3 tools

get_package_info_from_npmB

Get package basic information and dependencies from npm registry

ParametersJSON Schema

Name	Required	Description
`package_name`	Yes	The name of the npm package
`include_dependencies`	No	Whether to include dependencies
`include_dev_dependencies`	No	Whether to include development dependencies

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose behavior such as being read-only, network call, response structure, or any side effects. The agent must assume it is safe and non-destructive without confirmation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the action and resource. Every word is necessary; no fluff. Ideal for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the parameter count (3) and lack of output schema, the description is adequate but incomplete. It does not specify what 'basic information' includes nor the structure of the result. For a tool returning data, more detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all three parameters, each with clear descriptions. The tool description adds no additional parameter context beyond what the schema already provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Get') and resource ('package basic information and dependencies') from npm registry. It distinguishes from siblings like get_readme_from_npm and search_packages_from_npm by specifying 'basic information and dependencies', though 'basic information' is somewhat vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool over alternatives. The description does not mention when to choose it over get_readme_from_npm or search_packages_from_npm, leaving the agent to infer from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_readme_from_npmB

Get package README and usage examples from npm registry

ParametersJSON Schema

Name	Required	Description	Default
`package_name`	Yes	The name of the npm package
`version`	No	The version of the package	latest
`include_examples`	No	Whether to include usage examples

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It only states the function but fails to disclose whether it is read-only, error handling, or any constraints like missing packages or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single clear sentence with no fluff. Every word adds value and is appropriately front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description lacks details on response format, error scenarios (e.g., package not found), version format, or source. More context is needed for a tool fetching external data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning over the schema—'usage examples' ties to include_examples param but is already described in schema. No new insight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states 'Get package README and usage examples from npm registry', clearly identifying the verb and resource. The tool name and description directly differentiate it from siblings like get_package_info_from_npm which likely returns metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving README and examples but does not explicitly state when to use this tool versus alternatives like get_package_info_from_npm or search_packages_from_npm.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_packages_from_npmB

Search for packages in npm registry

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The search query
`limit`	No	Maximum number of results to return
`quality`	No	Minimum quality score (0-1)
`popularity`	No	Minimum popularity score (0-1)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for disclosing behavioral traits. It only states the action without indicating read-only nature, rate limits, or potential side effects. For a read operation, such omissions are significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no superfluous words. However, it could be slightly more informative without losing conciseness, e.g., by mentioning sorting or result fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has four parameters, no output schema, and no annotations, the description is insufficient. It lacks details on search behavior, result structure, pagination, and any ordering or filtering nuances, leaving the agent with incomplete information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no meaning beyond the schema; it does not explain the semantics of quality or popularity scores. The default and bounds for limit are in the schema, but contextual meaning is missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'packages in npm registry'. It effectively distinguishes from sibling tools like get_package_info_from_npm and get_readme_from_npm, which are for retrieving details or readme of specific packages, not for searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives is provided. The context is implied by the tool name and sibling list, but the description itself does not clarify when searching is appropriate or when to use the other tools instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.6Jun 9, 2026

Changedget_package_info_from_npm3 fields changed

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

changedInput schema / properties / include_dependencies / description

Previous value: -"Whether to include dependencies (default: true)"New value: +"Whether to include dependencies"

changedInput schema / properties / include_dev_dependencies / description

Previous value: -"Whether to include development dependencies (default: false)"New value: +"Whether to include development dependencies"

Changedget_readme_from_npm3 fields changed

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

changedInput schema / properties / include_examples / description

Previous value: -"Whether to include usage examples (default: true)"New value: +"Whether to include usage examples"

changedInput schema / properties / version / description

Previous value: -"The version of the package (default: \"latest\")"New value: +"The version of the package"

Changedsearch_packages_from_npm3 fields changed

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

changedInput schema / properties / limit / description

Previous value: -"Maximum number of results to return (default: 20)"New value: +"Maximum number of results to return"

changedInput schema / properties / limit / type

Previous value: -"number"New value: +"integer"

3 tool updatesv0.1.5Jun 7, 2026
- First observedget_package_info_from_npm
- First observedget_readme_from_npm
- First observedsearch_packages_from_npm

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-09-09 18:30 across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: searching for packages, retrieving package metadata, and fetching README content. There is no ambiguity between searching and retrieving specific package resources.

Naming Consistency5/5

All three tool names follow a consistent verb_noun_from_npm pattern (get_readme, get_package_info, search_packages). The verb choice appropriately reflects each action, and the structure is uniform throughout.

Tool Count4/5

Three tools is on the lean side, but the server has a narrow, focused purpose (npm package readme retrieval), so each tool earns its place. The count feels slightly thin rather than excessive or insufficient.

Completeness4/5

The core workflow is covered: search for a package, inspect its metadata, then fetch its README. Minor gaps exist, such as fetching version-specific readmes or resolving readmes from alternate sources, but there are no dead ends for the stated purpose.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

npm A
io.github.pipeworx-io
npm MCP — wraps the npm Registry API (free, no auth)
Developer Tools Search API Testing
2
Npm Package Info Mcp
io.github.varvararatta
Dive into the world of npm with our NPM Package Info MCP. Access crucial metadata about any npm
Developer Tools Search
2
SkillAgent A
dev.skillagent
Search and fetch AI agent skills, rules files and MCP servers indexed from GitHub.
Autonomous Agents Developer Tools Search
41
developer-tools-mcp-server A
com.thenextgennexus
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Developer Tools Search
72

Related MCP Servers

npm-search-mcp-server
Search Developer Tools
btwiuse
A
license
C
quality
F
maintenance
MCP server for searching npm packages
Updated 7 months ago (2026-02-20 23:48 UTC)
1
162 npm
16
MIT
npm-docs-server
Documentation Access Developer Tools
bsmi021
A
license
Not graded
quality
D
maintenance
Fetches metadata and README documentation for NPM packages, with local caching via SQLite for improved performance.
Updated a year ago (2025-04-03 21:42 UTC)
3
MIT
@kongyo2/npm-info-mcp-server
Developer Tools Code Analysis
kongyo2
A
license
A
quality
C
maintenance
MCP server that provides npm package information for AI agents during TypeScript development.
Updated 3 days ago (2026-09-21 07:13 UTC)
7
5 npm
1
MIT
mcp-npm-tools
Developer Tools Code Analysis
rog0x
A
license
A
quality
D
maintenance
MCP server providing npm registry search, package details, dependency auditing, bundle size estimation, and package comparison tools for AI agents.
Updated 6 months ago (2026-03-21 20:21 UTC)
5
27 npm
MIT