npm package: @illuminaresolutions/mcp-server-scanner
Description: MCP server for scanning and analyzing other MCP servers
Author: Nick Bostic
Latest version: 3.3.1

# MCP Server Scanner

<!--
TODO: Add Smithery badge once registered
-->
[![npm version](https://img.shields.io/npm/v/@illuminaresolutions/mcp-server-scanner.svg)](https://www.npmjs.com/package/@illuminaresolutions/mcp-server-scanner)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for scanning and analyzing other MCP servers installed in Claude Desktop, Cline, or other MCP clients. This tool helps you inspect and verify your MCP server configurations, ensuring optimal setup and compatibility.

![MCP Server Scanner - scan-servers command](docs/images/mcp-server-scan-servers-example.png)

![MCP Server Scanner - route-request command](docs/images/mcp-server-route-request-example.png)

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
  - [Using Smithery](#using-smithery)
  - [Using npm](#using-npm)
  - [Client Configuration](#client-configuration)
    - [Cline](#cline)
    - [Claude Desktop](#claude-desktop)
- [Usage](#usage)
  - [scan-servers](#scan-servers)
  - [route-request](#route-request)
- [Example Prompts](#example-prompts)
- [Development](#development)
- [Debugging](#debugging)
- [Contributing](#contributing)
- [License](#license)

## Features

- **Comprehensive Server Analysis**
  - List all configured MCP servers in your environment
  - Display detailed server configurations
  - Verify environment variable usage

- **Intelligent Request Routing**
  - Natural language query analysis
  - Smart matching to appropriate MCP tools
  - Detailed routing explanations

- **Cross-Platform Support**
  - macOS and Windows compatibility
  - Consistent behavior across platforms
  - Platform-specific path handling

- **Robust Error Handling**
  - Graceful handling of missing configurations
  - Clear error messages
  - Recovery suggestions

## Quick Start

```bash
# Install via Smithery (recommended)
npx @smithery/cli install @illuminaresolutions/mcp-server-scanner --client claude

# Or install globally via npm
npm install -g @illuminaresolutions/mcp-server-scanner
```

## Installation

### Using Smithery

The fastest way to get started is using Smithery:

```bash
npx @smithery/cli install @illuminaresolutions/mcp-server-scanner --client claude
```

### Using npm

For better performance and offline availability:

```bash
npm install -g @illuminaresolutions/mcp-server-scanner
```

### Client Configuration

#### Cline

Add to your Cline MCP settings:

```json
{
  "mcpServers": {
    "scanner": {
      "command": "mcp-server-scanner"
    }
  }
}
```

For npx installation:
```json
{
  "mcpServers": {
    "scanner": {
      "command": "npx",
      "args": ["-y", "@illuminaresolutions/mcp-server-scanner"]
    }
  }
}
```

#### Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%/Claude/claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "scanner": {
      "command": "mcp-server-scanner"
    }
  }
}
```

## Usage

### scan-servers

Lists and analyzes all configured MCP servers in your environment.

```typescript
// Tool call
{
  "name": "scan-servers",
  "arguments": {}
}

// Example response
{
  "servers": [
    {
      "name": "puppeteer",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "environmentVariables": []
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "environmentVariables": ["GITHUB_TOKEN"]
    }
  ]
}
```

### route-request

Routes natural language queries to the most appropriate MCP tool.

```typescript
interface RouteRequestArgs {
  query: string;
  context?: Record<string, unknown>;
}

// Example usage
{
  "name": "route-request",
  "arguments": {
    "query": "Convert this markdown file to PDF",
    "context": {
      "fileType": "markdown",
      "targetFormat": "pdf"
    }
  }
}

// Example response
{
  "tool": "mcp-pandoc.convert-contents",
  "score": 3,
  "explanation": "Selected based on format conversion capabilities and keyword matches"
}
```

## Example Prompts

### Server Analysis
- "What MCP servers do I have installed?"
- "Show me my MCP server configurations"
- "Which servers use environment variables?"

### Request Routing
- "What's the best MCP tool for converting files?"
- "Route my request to create a GitHub issue"
- "Find the right tool to search the web"

## Development

### Prerequisites

- Node.js 16 or higher
- npm 7 or higher

### Setup

```bash
# Clone the repository
git clone https://github.com/illuminaresolutions/mcp-server-scanner.git

# Install dependencies
npm install

# Build the project
npm run build
```

### Testing

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage
```

## Debugging

### MCP Inspector

Debug with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector mcp-server-scanner
```

### Log Access

View server logs:

```bash
# macOS/Linux
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-scanner.log

# Windows (PowerShell)
Get-Content -Path "$env:APPDATA\Claude\mcp-server-scanner.log" -Tail 20 -Wait
```

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:

- Code of Conduct
- Development process
- Pull request process
- Coding standards

## Security

For security issues, please see our [Security Policy](SECURITY.md).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.