ls-mcp
Detect Configured MCP (Model Context Protocol) in your local dev environment
## Features
- **🔍 MCP Discovery**: Automatically detect MCP servers across various AI applications and agentic IDEs
- **📁 Directory Bubbling**: Intelligent discovery of project-scoped MCP configs from nested directories, supporting project-scoped MCP Server configuration and global configurations
- **🔄 Process Detection**: Real-time status of running MCP servers
- **🔒 Credential Analysis**: Security analysis of environment variables and API keys for potentially exposed credentials in MCP Servers
## Usage: CLI
```bash
npx ls-mcp
```
### Analyze Specific Files
To analyze specific MCP configuration files instead of using automatic discovery, use the `--files` flag. This flag **replaces** automatic discovery and only analyzes the files you specify:
```bash
# Single file
npx ls-mcp --files ./mcp-config.json
# Multiple files (comma-separated)
npx ls-mcp --files ./config1.json,./config2.json
# Multiple files (space-separated)
npx ls-mcp --files ./config1.json ./config2.json
```
The `--files` flag automatically detects the configuration structure in your files, supporting various formats including:
- `servers` - Standard MCP configuration key
- `mcpServers` - Alternative MCP configuration key
- `mcp.servers` - Nested configuration format
- `context_servers` - Context-based configuration format
### Show All Providers
By default, `ls-mcp` hides providers that have zero configured servers to reduce clutter. To show all providers including those with empty configurations, use the `--all` or `-a` flag:
```bash
# Show all providers including empty ones
npx ls-mcp --all
# Short form
npx ls-mcp -a
# Combine with JSON output
npx ls-mcp --all --json
```
**Note**: When using `--files` to analyze specific configuration files, the custom group is always shown even if it contains zero servers, as you explicitly requested to analyze those files.
### JSON Output
To output results in JSON format (useful for programmatic consumption):
```bash
npx ls-mcp --json
# Combine with --files flag
npx ls-mcp --files ./config.json --json
```
This will return a structured JSON object containing:
- `mcpFiles`: Complete MCP server configurations organized by provider (only includes providers with configured servers unless `--all` is specified)
- `summary`: Statistics including total servers, running servers, credential warnings, and transport breakdown
### Debug Mode
To enable verbose debugging output, set the `NODE_DEBUG` environment variable:
```bash
# Enable debug logging for ls-mcp
NODE_DEBUG=ls-mcp npx ls-mcp
# Enable all debug logging
NODE_DEBUG=* npx ls-mcp
```
## Documentation
For detailed information about the project architecture and features:
- **[Project Overview](./docs/project.md)**: Comprehensive project analysis and architecture
- **[Design Documentation](./docs/design.md)**: Technical design decisions and implementation details
- **[Requirements](./docs/requirements.md)**: Functional and non-functional requirements
- **[Custom File Analysis](./docs/custom-files-analysis.md)**: Analyze specific MCP configuration files with the `--files` flag
- **[Directory Bubbling](./docs/directory-bubbling.md)**: Intelligent directory traversal feature
- **[URL Hostname Extraction](./docs/url-hostname-extraction.md)**: Clean display of hostnames for URL-based servers
- **[Credential Detection](./docs/credential-detection.md)**: Security analysis features
## Documentation
- [Project documentation](./docs/README.md) - development, testing, architecture, and conventions.
## Contributing
Please consult [CONTRIBUTING](./CONTRIBUTING.md) for guidelines on contributing to this project.
## Author
**ls-mcp** © [Liran Tal](https://github.com/lirantal), Released under the [Apache-2.0](./LICENSE) License.
