Provides access to MCP servers listed in the Model Context Protocol GitHub repository, allowing AI assistants to discover available services
Uses Mermaid for rendering architecture and data flow diagrams to visualize the MCP Advisor system architecture
Incorporates Shields.io badges in the README to display MCP status and links to MCP servers
MCP Advisor
Introduction
MCP Advisor is a discovery and recommendation service that helps AI assistants explore Model Context Protocol (MCP) servers using natural language queries. It makes it easier for users to find and leverage MCP tools suitable for specific tasks.
Features
Natural Language Search: Find MCP services using conversational queries
Rich Metadata: Get detailed information about each service
Real-time Updates: Always in sync with the latest MCP services
Easy Integration: Simple configuration for any MCP-compatible AI assistant
Hybrid Search Engine: Advanced search capabilities combining vector search and text matching
Multi-provider Support: Support for multiple search providers executing in parallel
Documentation Navigation
Installation Guide - Detailed installation and configuration instructions
User Guide - How to use MCP Advisor
Architecture Documentation - System architecture details
Technical Details - Advanced technical features
Developer Guide - Development environment setup and code contribution
Best Practices - Coding standards and best practices for contributors
Troubleshooting - Common issues and solutions
Search Providers - Search provider details
API Reference - API documentation
Roadmap - Future development plans
Contribution Guidelines - How to contribute code
Quick Start
Installation
The fastest way is to integrate MCP Advisor through MCP configuration:
Add this configuration to your AI assistant's MCP settings file:
MacOS/Linux:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%AppData%\Claude\claude_desktop_config.json
For more installation methods, see the Installation Guide.
Demo
Developer Guide
Architecture Overview
MCP Advisor adopts a modular architecture with clear separation of concerns and functional programming principles:
Core Components
Search Service Layer
Unified search interface and provider aggregation
Support for multiple search providers executing in parallel
Configurable search options (limit, minSimilarity)
Search Providers
Meilisearch Provider: Vector search using Meilisearch
GetMCP Provider: API search from the GetMCP registry
Compass Provider: API search from the Compass registry
Offline Provider: Hybrid search combining text and vectors
Hybrid Search Strategy
Intelligent combination of text matching and vector search
Configurable weight balancing
Smart adaptive filtering mechanisms
Transport Layer
Stdio (CLI default)
SSE (Web integration)
REST API endpoints
For more detailed architecture documentation, see ARCHITECTURE.md.
Technical Highlights
Advanced Search Techniques
Vector Normalization
All vectors are normalized to unit length (magnitude = 1)
Ensures consistent cosine similarity calculations
Improves search precision by focusing on direction rather than magnitude
Parallel Search Execution
Vector search and text search run in parallel
Leverages Promise.all for optimal performance
Fallback mechanisms enabled if either search fails
Weighted Result Merging
Configurable weights between vector and text results
Default: vector similarity (70%), text matching (30%)
Error Handling and Logging System
MCP Advisor implements robust error handling and logging systems:
Contextual Error Formatting
Standardized error object enrichment
Stack trace preservation and formatting
Error type categorization and standardization
Graceful Degradation
Multi-provider fallback strategies
Partial result processing
Default responses for critical failures
For more technical details, see TECHNICAL_DETAILS.md.
Developer Quick Start
Development Environment Setup
Clone the repository
Install dependencies:
npm installConfigure environment variables (see INSTALLATION.md)
Library Usage
Transport Options
MCP Advisor supports multiple transport methods:
Stdio Transport (default) - Suitable for command-line tools
SSE Transport - Suitable for web integration
REST Transport - Provides REST API endpoints
For more development details, see DEVELOPER_GUIDE.md.
Contribution Guidelines
Follow commit message conventions:
Use lowercase types (feat, fix, docs, etc.)
Write descriptive messages in sentence format
Ensure code quality:
Run tests:
npm test
Check types:
npm run type-check
Lint code:
npm run lint
For detailed contribution guidelines, see CONTRIBUTING.md.
Usage Examples
Example Queries
Here are some example queries you can use with MCP Advisor:
Example Response
For more examples, see EXAMPLES.md.
Troubleshooting
Common Issues
Connection Refused
Ensure the server is running on the specified port
Check firewall settings
No Results Returned
Try a more general query
Check network connection to registry APIs
Performance Issues
Consider adding more specific search terms
Check server resources (CPU/memory)
For more troubleshooting information, see TROUBLESHOOTING.md.
Search Providers
MCP Advisor supports multiple search providers that can be used simultaneously:
Compass Search Provider: Retrieves MCP server information using the Compass API
GetMCP Search Provider: Uses the GetMCP API and vector search for semantic matching
Meilisearch Search Provider: Uses Meilisearch for fast, fault-tolerant text search
For detailed information about search providers, see SEARCH_PROVIDERS.md.
API Documentation
For detailed API documentation, see API_REFERENCE.md.
Roadmap
MCP Advisor is evolving from a simple recommendation system to an intelligent agent orchestration platform. Our vision is to create a system that not only recommends the right MCP servers but also learns from interactions and helps agents dynamically plan and execute complex tasks.
Major Development Phases
Recommendation Capability Optimization (2025 Q2-Q3)
Accept user feedback
Refine recommendation effectiveness
Introduce more indices
For a detailed roadmap, see ROADMAP.md.
Testing
Use inspector for testing:
License
This project is licensed under the MIT License - see the LICENSE file for details.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A discovery and recommendation service that helps AI assistants find Model Context Protocol servers based on natural language queries.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.Last updated -55MIT License
- AsecurityAlicenseAqualityEnables AI assistants to discover, retrieve details about, and manage MCP (Model Context Protocol) servers that provide additional tools and capabilities on demand.Last updated -5478AGPL 3.0
- -securityFlicense-qualityA comprehensive Model Context Protocol server that provides AI assistants with direct access to Semantic Scholar's academic database, enabling advanced paper discovery, citation analysis, author research, and AI-powered recommendations.Last updated -4
- -securityAlicense-qualityModel Context Protocol server that enables AI assistants to perform keyword research, SEO analysis, and content planning through natural language queries against kwrds.ai's SEO tools.Last updated -5Apache 2.0