MCP Search Server - Comprehensive Documentation 🚀

An intelligent MCP (Model Context Protocol) server that helps you discover and research MCP servers using the powerful Exa AI search engine. Built with FastMCP for seamless integration with AI assistants like Claude, Cursor, and more.

🎥 Demo

Watch the demo video to see the MCP Search Server in action:

🎬 View Demo on YouTube

Table of Contents

1. Demo

2. Features

3. Architecture

4. Quick Start

5. Installation Guide

6. Usage Guide

7. Configuration

8. API Reference

9. Integration

10. Troubleshooting

11. Contributing

12. License

🌟 Features

• Smart MCP Discovery: Search for MCP servers based on your specific requirements

• Intelligent Analysis: Automatically analyzes and ranks search results for MCP relevance

• Detailed Information: Get comprehensive details about specific MCP servers

• Similar MCPs: Find MCP servers similar to ones you already know

• Category Organization: MCPs organized by functional categories

• Direct Q&A: Ask specific questions about MCP servers and get direct answers

• Multiple Search Modes: Support for both broad and GitHub-focused searches

🏗️ Architecture

The server consists of several key components:

Core Components

1. ExaSearchClient: Handles interaction with Exa's search, answer, and find-similar APIs

2. MCPAnalyzer: Intelligent analysis engine that:

   • Identifies MCP-relevant content from search results

   • Calculates confidence scores based on multiple factors

   • Extracts structured information (features, categories, etc.)

   • Filters and ranks recommendations

3. MCPRecommendation: Data structure representing discovered MCPs with:

   • Name, description, and URLs

   • Repository information

   • Confidence scores

   • Key features and categories

   • Installation notes

Available Tools

🚀 Quick Start

Prerequisites

1. Python 3.10+

2. Exa API Key - Get one from Exa Dashboard

Installation

1. Clone and setup:

   git clone <this-repo> cd mcp-search-server pip install -r requirements.txt

2. Set your Exa API key:

   export EXA_API_KEY=your_api_key_here

3. Run the server:

   python mcp_search_server.py

Testing with FastMCP CLI

📦 Installation Guide

This guide covers installing and setting up the MCP Search Server on different operating systems.

📋 Prerequisites

Required:

• Python 3.10 or higher

• Exa API Key (get from Exa Dashboard)

• Internet connection for search functionality

Optional:

• Git for cloning repositories

• FastMCP CLI for testing and development

🐍 Python Installation

Windows

Option 1: Microsoft Store (Recommended)

1. Open Microsoft Store

2. Search for "Python 3.11" or "Python 3.12"

3. Click "Get" to install

4. Verify installation: python --version

Option 2: Python.org

1. Visit python.org/downloads

2. Download latest Python 3.10+ for Windows

3. Run installer with "Add to PATH" checked

4. Verify: python --version

Option 3: Chocolatey

macOS

Option 1: Homebrew (Recommended)

Option 2: Python.org

1. Visit python.org/downloads

2. Download latest Python 3.10+ for macOS

3. Run the installer

4. Verify: python3 --version

Linux (Ubuntu/Debian)

Linux (CentOS/RHEL/Fedora)

🚀 MCP Search Server Installation

Method 1: Direct Download and Setup

1. Download the files:

   # Create project directory mkdir mcp-search-server cd mcp-search-server # Download files (or copy from this project) # - mcp_search_server.py # - requirements.txt # - README.md # - test_mcp_search.py

2. Install dependencies:

   # Using pip pip install -r requirements.txt # Or install manually pip install fastmcp>=2.0.0 httpx>=0.25.0

3. Set up environment:

   # Linux/Mac export EXA_API_KEY=your_exa_api_key_here # Windows Command Prompt set EXA_API_KEY=your_exa_api_key_here # Windows PowerShell $env:EXA_API_KEY="your_exa_api_key_here"

Method 2: Using Virtual Environment (Recommended)

1. Create virtual environment:

   # Create virtual environment python -m venv mcp-search-env # Activate it # Linux/Mac: source mcp-search-env/bin/activate # Windows: mcp-search-env\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Run server:

   python mcp_search_server.py

🔑 Exa API Key Setup

1. Get API Key

1. Visit Exa Dashboard

2. Sign up or log in

3. Navigate to API Keys section

4. Create a new API key

5. Copy the key (starts with exa_)

2. Set Environment Variable

Temporary (Current Session)

Permanent Setup

Linux/Mac (~/.bashrc or ~/.zshrc):

Windows (System Environment Variables):

1. Open "Environment Variables" in Control Panel

2. Add new User Variable:

   • Name: EXA_API_KEY

   • Value: exa_your_key_here

3. Restart terminal/applications

✅ Verification and Testing

1. Basic Installation Test

2. API Key Test

3. Server Test

📚 Usage Guide

This guide walks you through setting up and using the MCP Search Server to discover and research MCP servers for your projects.

🛠️ Integration Methods

Method 1: Claude Desktop Integration

1. Locate Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add server configuration:

   { "mcpServers": { "mcp-search": { "command": "python", "args": ["/absolute/path/to/mcp_search_server.py"], "env": { "EXA_API_KEY": "your_exa_api_key_here" } } } }

3. Restart Claude Desktop

4. Test in Claude:

   • Type: "Search for database MCP servers"

   • Claude should now be able to use the MCP search tools

Method 2: Cursor Integration

1. Open Cursor settings

2. Navigate to MCP configuration

3. Add the MCP search server:

   { "command": "python", "args": ["/path/to/mcp_search_server.py"], "env": { "EXA_API_KEY": "your_api_key" } }

Method 3: Command Line Testing

Method 4: Programmatic Usage

🎯 Common Use Cases

Use Case 1: Finding MCPs for Specific Tasks

Goal: Find MCPs for database operations

Steps:

1. Use the search_mcps tool

2. Provide requirement: "database access and SQL operations"

3. Review confidence scores and categories

4. Get detailed info with get_mcp_details

Example interaction:

Use Case 2: Exploring MCP Categories

Goal: Understand what MCPs are available in different areas

Steps:

1. Use categorize_mcps tool

2. Provide broad requirement like "file management"

3. Explore different categories returned

4. Drill down into specific categories

Example interaction:

Use Case 3: Research and Comparison

Goal: Compare similar MCPs

Steps:

1. Find initial MCP with search_mcps

2. Use find_similar_mcps to find alternatives

3. Use get_mcp_details for detailed comparison

4. Ask specific questions with ask_mcp_question

Example interaction:

Use Case 4: General Questions

Goal: Get expert answers about MCPs

Steps:

1. Use ask_mcp_question tool

2. Ask specific questions about MCP ecosystem

3. Get answers with citations

4. Follow up with more specific searches

Example interaction:

📋 Available Tools Reference

1. search_mcps

Purpose: Search for MCPs based on requirements

Parameters:

• requirement (string): What you need (e.g., "database access")

• max_results (int, default=10): Number of results

• include_github_only (bool, default=false): Limit to GitHub repos

Returns: JSON with MCP recommendations, confidence scores, categories

2. get_mcp_details

Purpose: Get detailed information about a specific MCP

Parameters:

• mcp_url (string): URL of the MCP repository or documentation

Returns: Detailed MCP information including similar MCPs

3. find_similar_mcps

Purpose: Find MCPs similar to a reference MCP

Parameters:

• reference_mcp_url (string): URL of reference MCP

• max_results (int, default=5): Number of similar MCPs

Returns: List of similar MCPs with comparison data

4. ask_mcp_question

Purpose: Ask specific questions about MCPs

Parameters:

• question (string): Your question about MCP servers

Returns: Direct answer with citations and sources

5. categorize_mcps

Purpose: Get MCPs organized by categories

Parameters:

• requirement (string): Requirement to categorize MCPs for

Returns: MCPs grouped by functional categories

🔍 Understanding Results

Confidence Scores

• 0.8-1.0: Highly relevant, definitely an MCP

• 0.6-0.8: Likely relevant, probably an MCP

• 0.4-0.6: Possibly relevant, might be related

• 0.2-0.4: Low relevance, worth checking

• 0.0-0.2: Minimal relevance

Categories

• Database & Storage: SQL, NoSQL, file storage

• Web & APIs: HTTP clients, REST APIs, scraping

• File System: File operations, directory management

• Communication: Slack, Discord, email integration

• Development Tools: Git, CI/CD, testing tools

• AI & ML: Machine learning, model integration

• Utilities: General-purpose tools and helpers

Key Features

Automatically extracted capabilities:

• Database operations

• API integration

• File management

• Web scraping

• Communication tools

• Development utilities

🔧 Configuration

Environment Variables

• EXA_API_KEY (required): Your Exa AI API key

Server Configuration

The server can be run with different transports:

📊 API Reference

Tool Parameters

search_mcps

• requirement (str): Description of what you need

• max_results (int, default=10): Number of results to return

• include_github_only (bool, default=False): Limit to GitHub repositories

get_mcp_details

• mcp_url (str): URL of the MCP server or repository

find_similar_mcps

• reference_mcp_url (str): URL of reference MCP

• max_results (int, default=5): Number of similar MCPs to find

ask_mcp_question

• question (str): Your question about MCP servers

categorize_mcps

• requirement (str): Requirement to categorize MCPs for

Response Format

All tools return structured JSON with:

• Clear data organization

• Confidence scores where applicable

• Rich metadata (categories, features, etc.)

• Error handling with descriptive messages

🛠️ Integration

With Claude Desktop

Add to your claude_desktop_config.json:

With Cursor

Configure in your MCP settings to enable MCP discovery within Cursor.

Programmatic Access

🚨 Troubleshooting

Common Issues

Issue: "python: command not found"

Solutions:

• Install Python (see Python Installation section)

• Use python3 instead of python

• Check if Python is in PATH

Issue: "No module named 'fastmcp'"

Solutions:

Issue: "EXA_API_KEY environment variable is required"

Solutions:

• Set the environment variable (see Exa API Key Setup)

• Check if variable is set: echo $EXA_API_KEY (Linux/Mac) or echo %EXA_API_KEY% (Windows)

• Restart terminal after setting environment variable

Issue: Permission errors during installation

Solutions:

Issue: "SSL Certificate verify failed"

Solutions:

Issue: "Error searching for MCPs: HTTP 401"

Solution: Check that your Exa API key is valid and active

Issue: "No MCPs found for requirement"

Solutions:

• Try broader search terms

• Use different keywords

• Check if the requirement is too specific

Issue: Tool returns empty results

Solutions:

• Verify internet connection

• Try different search terms

• Check Exa API status

Platform-Specific Issues

Windows PowerShell Execution Policy

If you get execution policy errors:

macOS Permission Issues

If you get permission errors:

Linux Missing Development Headers

If compilation fails:

Performance Tips

1. Use specific requirements for better results

2. Start with broader searches then narrow down

3. Check confidence scores to gauge relevance

4. Use GitHub-only search for higher quality results

5. Try category search for exploration

API Limits

• Exa API has rate limits based on your plan

• The server respects these limits automatically

• Consider caching results for frequently searched terms

• Use smaller max_results values for faster responses

🎓 Best Practices

1. Search Strategy

• Start broad, then narrow down

• Use domain-specific terminology

• Try multiple phrasings of requirements

• Check confidence scores before diving deep

2. Result Evaluation

• Review confidence scores (>0.6 recommended)

• Check repository activity and stars

• Read descriptions carefully

• Verify installation requirements

3. Integration Tips

• Test server standalone before integrating

• Use absolute paths in configurations

• Set environment variables properly

• Monitor error logs for issues

4. Workflow Optimization

• Save useful MCP URLs for future reference

• Use categorization for discovery

• Ask follow-up questions for clarification

• Compare similar MCPs before choosing

🔍 How It Works

Search Intelligence

The system uses multiple signals to identify and rank MCP servers:

1. Content Analysis: Scans for MCP-specific keywords and indicators

2. Source Credibility: Prioritizes GitHub repositories and official documentation

3. Exa Scoring: Leverages Exa's semantic understanding

4. Feature Extraction: Automatically identifies key capabilities

5. Category Classification: Groups MCPs by functional area

Quality Scoring

Each MCP recommendation includes a confidence score based on:

• Presence of MCP-specific terminology

• Repository quality indicators

• Documentation completeness

• Exa's semantic relevance score

🧪 Testing

Run the server in development mode:

🔒 Security & Privacy

• API Key Security: Exa API key required but never logged or exposed

• Read-Only Operations: Server only performs search operations, no modifications

• Error Handling: Graceful degradation with informative error messages

• Rate Limiting: Respects Exa API rate limits

🚦 Limitations

• Requires Exa API key (paid service)

• Search quality depends on Exa's index coverage

• Results limited by Exa's rate limits

• MCP detection based on content analysis (may have false positives/negatives)

🎯 Use Cases

For Developers

• Discover Tools: Find MCPs that solve specific development challenges

• Evaluate Options: Compare different MCPs for the same use case

• Learn: Understand what MCPs are available in the ecosystem

For AI Assistants

• Recommendation Engine: Provide intelligent MCP recommendations to users

• Research Tool: Help users find the right tools for their projects

• Knowledge Base: Answer questions about the MCP ecosystem

For Teams

• Standardization: Find approved MCPs for team use

• Documentation: Maintain knowledge of available tools

• Discovery: Stay updated with new MCP releases

🤝 Contributing

Contributions welcome! Areas for improvement:

1. Enhanced Analysis: Better MCP detection algorithms

2. Caching: Add result caching for performance

3. Filtering: Additional filtering options

4. Exports: Export capabilities for found MCPs

5. Monitoring: Usage analytics and performance monitoring

📞 Getting Help

Built-in Help

Access the help resource: mcp-search://help

Error Messages

The server provides detailed error messages with troubleshooting tips

Testing

Use the test script to verify functionality:

Support Resources

• FastMCP Documentation: https://gofastmcp.com

• Exa AI Documentation: https://docs.exa.ai

• Model Context Protocol: https://modelcontextprotocol.io

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• FastMCP Documentation

• Model Context Protocol

• Exa AI

• Get Exa API Key

🆘 Support

• Check the built-in help: Use the mcp-search://help resource

• Review error messages for troubleshooting guidance

• Ensure EXA_API_KEY is properly set

• Verify network connectivity to Exa API

Built with ❤️ using FastMCP and Exa AI

Happy MCP discovering! 🚀