# Directory Structure
```
├── .gitignore
├── Dockerfile
├── index.ts
├── LICENSE
├── logo.png
├── package.json
├── README.md
├── screenshot.png
├── smithery.yaml
├── tsconfig.base.json
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
dist/
node_modules/
*.lock
package-lock.json
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
[](https://mseep.ai/app/btwiuse-npm-search-mcp-server)
# npm-search MCP Server
[](https://smithery.ai/server/npm-search-mcp-server)
A Model Context Protocol server that allows you to search for npm packages by calling the `npm search` command.
<a href="https://glama.ai/mcp/servers/yeb3luefvf"><img width="380" height="200" src="https://glama.ai/mcp/servers/yeb3luefvf/badge" alt="npm-search-mcp-server MCP server" /></a>
### Available Tools
- `search_npm_packages` - Search for npm packages.
- Required arguments:
- `query` (string): The search query.
## Installation
### Installing via Smithery
To install npm-search for Claude Desktop automatically via [Smithery](https://smithery.ai/server/npm-search-mcp-server):
```bash
npx -y @smithery/cli install npm-search-mcp-server --client claude
```
### Using NPM (recommended)
Alternatively you can install `npm-search-mcp-server` via npm:
```bash
npm install -g npm-search-mcp-server
```
After installation, you can run it as a command using:
```bash
npm-search-mcp-server
```
### Using uv
When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *npm-search-mcp-server*.
## Configuration
### Configure for Claude.app
Add to your Claude settings:
<details>
<summary>Using npm installation</summary>
```json
"mcpServers": {
"npm-search": {
"command": "npx",
"args": ["-y", "npm-search-mcp-server"]
}
}
```
</details>
<details>
<summary>Using uvx</summary>
```json
"mcpServers": {
"npm-search": {
"command": "uvx",
"args": ["npm-search-mcp-server"]
}
}
```
</details>
### Configure for Zed
Add to your Zed settings.json:
<details>
<summary>Using npm installation</summary>
```json
"context_servers": {
"npm-search-mcp-server": {
"command": "npx",
"args": ["-y", "npm-search-mcp-server"]
}
},
```
</details>
<details>
<summary>Using uvx</summary>
```json
"context_servers": [
"npm-search-mcp-server": {
"command": "uvx",
"args": ["npm-search-mcp-server"]
}
],
```
</details>
## Example Interactions
1. Search for npm packages:
```json
{
"name": "search_npm_packages",
"arguments": {
"query": "express"
}
}
```
Response:
```json
{
"results": [
{
"name": "express",
"description": "Fast, unopinionated, minimalist web framework",
"version": "4.17.1",
"author": "TJ Holowaychuk",
"license": "MIT"
},
...
]
}
```
## Debugging
You can use the MCP inspector to debug the server. For uvx installations:
```bash
npx @modelcontextprotocol/inspector npx -y npm-search-mcp-server
```
Or if you've installed the package in a specific directory or are developing on it:
```bash
cd path/to/servers/src/npm-search
npx @modelcontextprotocol/inspector uv run npm-search-mcp-server
```
## Examples of Questions for Claude
1. "Search for express package on npm"
2. "Find packages related to react"
3. "Show me npm packages for web development"
## Build
Docker build:
```bash
cd src/npm-search
docker build -t mcp/npm-search .
```
## Contributing
We encourage contributions to help expand and improve npm-search-mcp-server. Whether you want to add new npm-related tools, enhance existing functionality, or improve documentation, your input is valuable.
For examples of other MCP servers and implementation patterns, see:
https://github.com/modelcontextprotocol/servers
Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make npm-search-mcp-server even more powerful and useful.
## License
npm-search-mcp-server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "."
},
"include": [
"./**/*.ts"
]
}
```
--------------------------------------------------------------------------------
/tsconfig.base.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
type: object
required: []
properties: {}
commandFunction:
# A function that produces the CLI command to start the MCP on stdio.
|-
config => ({command:'node', args:['dist/index.js']})
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
# Stage 1: Build the application
FROM node:20 AS builder
# Set the working directory
WORKDIR /app
# Copy package.json and package-lock.json
COPY package.json tsconfig.json ./
# Install dependencies
RUN npm install
# Copy the rest of the application
COPY . .
# Build the application
RUN npm run build
# Stage 2: Run the application
FROM node:20-alpine
# Set the working directory
WORKDIR /app
# Copy the build output and package files from the builder stage
COPY --from=builder /app/dist /app/dist
COPY --from=builder /app/package.json /app/package-lock.json /app/node_modules /app/
# Set the entrypoint
ENTRYPOINT ["node", "dist/index.js"]
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "npm-search-mcp-server",
"version": "0.1.1",
"description": "MCP server for searching npm",
"license": "MIT",
"author": "Anthropic, PBC (https://anthropic.com)",
"homepage": "https://modelcontextprotocol.io",
"repository": "https://github.com/btwiuse/npm-search-mcp-server",
"bugs": "https://github.com/modelcontextprotocol/servers/issues",
"type": "module",
"bin": {
"npm-search-mcp-server": "dist/index.js"
},
"files": [
"dist"
],
"scripts": {
"build": "tsc && shx chmod +x dist/*.js",
"prepare": "npm run build",
"watch": "tsc --watch"
},
"dependencies": {
"@modelcontextprotocol/sdk": "1.0.1"
},
"devDependencies": {
"@types/node": "^22.10.5",
"shx": "^0.3.4",
"typescript": "^5.6.2"
}
}
```
--------------------------------------------------------------------------------
/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ErrorCode,
ListToolsRequestSchema,
McpError,
} from '@modelcontextprotocol/sdk/types.js';
import { exec } from 'child_process';
import util from 'util';
const execPromise = util.promisify(exec);
const isValidSearchArgs = (args: any): args is { query: string } =>
typeof args === 'object' && args !== null && typeof args.query === 'string';
class NpmSearchServer {
private server: Server;
constructor() {
this.server = new Server(
{
name: 'npm-search-server',
version: '0.1.0',
},
{
capabilities: {
tools: {},
},
}
);
this.setupToolHandlers();
// Error handling
this.server.onerror = (error) => console.error('[MCP Error]', error);
process.on('SIGINT', async () => {
await this.server.close();
process.exit(0);
});
}
private setupToolHandlers() {
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'search_npm_packages', // Unique identifier
description: 'Search for npm packages', // Human-readable description
inputSchema: {
// JSON Schema for parameters
type: 'object',
properties: {
query: {
type: 'string',
description: 'Search query',
},
},
required: ['query'], // Array of required property names
},
},
],
}));
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name !== 'search_npm_packages') {
throw new McpError(
ErrorCode.MethodNotFound,
`Unknown tool: ${request.params.name}`
);
}
if (!isValidSearchArgs(request.params.arguments)) {
throw new McpError(
ErrorCode.InvalidParams,
'Invalid search arguments'
);
}
const query = request.params.arguments.query;
try {
const { stdout, stderr } = await execPromise(`npm search ${query}`);
if (stderr) {
throw new McpError(
ErrorCode.InternalError,
`npm search error: ${stderr}`
);
}
return {
content: [
{
type: 'text',
text: stdout,
},
],
};
} catch (error) {
if (error instanceof McpError) {
throw error;
}
if (error instanceof Error) {
throw new McpError(
ErrorCode.InternalError,
`Unexpected error: ${error.message}`
);
}
throw new McpError(
ErrorCode.InternalError,
'Unexpected error occurred'
);
}
});
}
async run() {
const transport = new StdioServerTransport();
await this.server.connect(transport);
console.error('Npm Search MCP server running on stdio');
}
}
const server = new NpmSearchServer();
server.run().catch(console.error);
```