NPM Package README MCP Server
bradford-tech/npm-package-readme-mcp-server
Acessa READMEs, metadados e estatísticas de pacotes npm via MCP
Ver no GitHubUm servidor MCP que expõe dados do registro npm — READMEs de pacotes, metadados e busca — para clientes IA compatíveis. Recupera informações do npm registry com fallback para GitHub API e inclui cache em memória para otimizar requisições.
Instalação
npx convez-ai bradford-tech/npm-package-readme-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Buscar documentação de pacotes npm programaticamente
- Extrair exemplos de uso de READMEs durante desenvolvimento
- Pesquisar pacotes por critérios de qualidade e popularidade
- Obter dependências e metadados de projetos para análise
- Integrar dados npm em agentes IA e workflows automatizados
Veredito

MCP server bem construído que democratiza o acesso a dados npm via Claude e clientes IA. Implementação madura (fork mantido), com caching inteligente e tratamento sensato de fallbacks GitHub — útil para quem trabalha com automação ao redor do ecossistema Node.js.
README
A tradução para o português deste README ainda está na fila.
@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-techscope after the original was removed from GitHub and npm. No functional changes from the upstream0.1.4release.
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
repositoryfield 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.