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

Demo
Features
Architecture
Quick Start
Installation Guide
Usage Guide
Configuration
API Reference
Integration
Troubleshooting
Contributing
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

ExaSearchClient: Handles interaction with Exa's search, answer, and find-similar APIs
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
MCPRecommendation: Data structure representing discovered MCPs with:
- Name, description, and URLs
- Repository information
- Confidence scores
- Key features and categories
- Installation notes

Available Tools

Tool	Description	Use Case
`search_mcps`	Search for MCPs based on requirements	"I need an MCP for database access"
`get_mcp_details`	Get detailed info about a specific MCP	Analyze a specific GitHub repo
`find_similar_mcps`	Find MCPs similar to a reference	Discover alternatives to known MCPs
`ask_mcp_question`	Ask specific questions about MCPs	"What are the best MCPs for web scraping?"
`categorize_mcps`	Get MCPs organized by categories	Explore MCPs by functional area

🚀 Quick Start

Prerequisites

Python 3.10+
Exa API Key - Get one from Exa Dashboard

Installation

Clone and setup:

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

Set your Exa API key:
```
export EXA_API_KEY=your_api_key_here
```
Run the server:
```
python mcp_search_server.py
```

Testing with FastMCP CLI

# Test the server interactively
fastmcp dev mcp_search_server.py

# Or inspect with web UI
fastmcp inspect mcp_search_server.py

📦 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)

Open Microsoft Store
Search for "Python 3.11" or "Python 3.12"
Click "Get" to install
Verify installation: python --version

Option 2: Python.org

Visit python.org/downloads
Download latest Python 3.10+ for Windows
Run installer with "Add to PATH" checked
Verify: python --version

Option 3: Chocolatey

# Install Chocolatey first (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Python
choco install python

macOS

Option 1: Homebrew (Recommended)

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.11

Option 2: Python.org

Visit python.org/downloads
Download latest Python 3.10+ for macOS
Run the installer
Verify: python3 --version

Linux (Ubuntu/Debian)

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-pip python3.11-venv

# Verify installation
python3.11 --version

Linux (CentOS/RHEL/Fedora)

# Fedora
sudo dnf install python311 python311-pip

# CentOS/RHEL (with EPEL)
sudo yum install python311 python311-pip

🚀 MCP Search Server Installation

Method 1: Direct Download and Setup

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

Install dependencies:

# Using pip
pip install -r requirements.txt

# Or install manually
pip install fastmcp>=2.0.0 httpx>=0.25.0

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)

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

Install dependencies:
```
pip install -r requirements.txt
```
Run server:
```
python mcp_search_server.py
```

🔑 Exa API Key Setup

1. Get API Key

Visit Exa Dashboard
Sign up or log in
Navigate to API Keys section
Create a new API key
Copy the key (starts with exa_)

2. Set Environment Variable

Temporary (Current Session)

# Linux/Mac
export EXA_API_KEY=exa_your_key_here

# Windows Command Prompt
set EXA_API_KEY=exa_your_key_here

# Windows PowerShell
$env:EXA_API_KEY="exa_your_key_here"

Permanent Setup

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

echo 'export EXA_API_KEY=exa_your_key_here' >> ~/.bashrc
source ~/.bashrc

Windows (System Environment Variables):

Open "Environment Variables" in Control Panel
Add new User Variable:
- Name: EXA_API_KEY
- Value: exa_your_key_here
Restart terminal/applications

✅ Verification and Testing

1. Basic Installation Test

# Test Python installation
python --version

# Test package imports
python -c "import fastmcp, httpx; print('Dependencies OK')"

2. API Key Test

# Test environment variable
python -c "import os; print('API Key:', 'Set' if os.getenv('EXA_API_KEY') else 'Not Set')"

3. Server Test

# Run test script
python test_mcp_search.py

# Or run server directly
python mcp_search_server.py

📚 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

Locate Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

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"
      }
    }
  }
}

Restart Claude Desktop
Test in Claude:
- Type: "Search for database MCP servers"
- Claude should now be able to use the MCP search tools

Method 2: Cursor Integration

Open Cursor settings
Navigate to MCP configuration

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

# Interactive testing with FastMCP CLI
fastmcp dev mcp_search_server.py

# Web-based inspector
fastmcp inspect mcp_search_server.py

Method 4: Programmatic Usage

import asyncio
import json
from fastmcp import Client

async def search_for_mcps():
    async with Client("mcp_search_server.py") as client:
        # Search for MCPs
        result = await client.call_tool("search_mcps", {
            "requirement": "database access",
            "max_results": 5
        })
        
        data = json.loads(result.text)
        print(f"Found {data['total_found']} MCPs")
        
        for rec in data['recommendations']:
            print(f"- {rec['name']}: {rec['description']}")

# Run the search
asyncio.run(search_for_mcps())

🎯 Common Use Cases

Use Case 1: Finding MCPs for Specific Tasks

Goal: Find MCPs for database operations

Steps:

Use the search_mcps tool
Provide requirement: "database access and SQL operations"
Review confidence scores and categories
Get detailed info with get_mcp_details

Example interaction:

User: "I need an MCP for SQLite database access"
Tool: search_mcps(requirement="SQLite database access", max_results=5)
Result: List of SQLite-related MCPs with confidence scores

Use Case 2: Exploring MCP Categories

Goal: Understand what MCPs are available in different areas

Steps:

Use categorize_mcps tool
Provide broad requirement like "file management"
Explore different categories returned
Drill down into specific categories

Example interaction:

User: "What file management MCPs are available?"
Tool: categorize_mcps(requirement="file management")
Result: MCPs grouped by categories (File System, Cloud Storage, etc.)

Use Case 3: Research and Comparison

Goal: Compare similar MCPs

Steps:

Find initial MCP with search_mcps
Use find_similar_mcps to find alternatives
Use get_mcp_details for detailed comparison
Ask specific questions with ask_mcp_question

Example interaction:

User: "Find alternatives to the FastMCP file server"
Tool: find_similar_mcps(reference_mcp_url="https://github.com/example/fastmcp-file")
Result: List of similar MCPs with comparison data

Use Case 4: General Questions

Goal: Get expert answers about MCPs

Steps:

Use ask_mcp_question tool
Ask specific questions about MCP ecosystem
Get answers with citations
Follow up with more specific searches

Example interaction:

User: "What are the most popular MCPs for web scraping?"
Tool: ask_mcp_question(question="most popular MCPs for web scraping")
Result: Direct answer with citations and source links

📋 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

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:

# STDIO (default) - for local use
mcp.run()

# HTTP Streaming - for web deployment
mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

# SSE - for compatibility
mcp.run(transport="sse", host="127.0.0.1", port=8000)

📊 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:

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

With Cursor

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

Programmatic Access

from fastmcp import Client

async def main():
    async with Client("mcp_search_server.py") as client:
        result = await client.call_tool("search_mcps", {
            "requirement": "file management",
            "max_results": 5
        })
        print(result.text)

🚨 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:

# Install missing dependencies
pip install fastmcp httpx

# Or reinstall from requirements
pip install -r requirements.txt

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:

# Use --user flag
pip install --user -r requirements.txt

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate    # Windows
pip install -r requirements.txt

Issue: "SSL Certificate verify failed"

Solutions:

# Upgrade certificates
pip install --upgrade certifi

# Or use --trusted-host (temporary fix)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org fastmcp

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:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS Permission Issues

If you get permission errors:

# Use Homebrew Python instead of system Python
brew install python@3.11
export PATH="/opt/homebrew/bin:$PATH"

Linux Missing Development Headers

If compilation fails:

# Ubuntu/Debian
sudo apt install python3-dev build-essential

# CentOS/RHEL
sudo yum install python3-devel gcc

Performance Tips

Use specific requirements for better results
Start with broader searches then narrow down
Check confidence scores to gauge relevance
Use GitHub-only search for higher quality results
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:

Content Analysis: Scans for MCP-specific keywords and indicators
Source Credibility: Prioritizes GitHub repositories and official documentation
Exa Scoring: Leverages Exa's semantic understanding
Feature Extraction: Automatically identifies key capabilities
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:

# Interactive testing
fastmcp dev mcp_search_server.py

# Web-based inspector
fastmcp inspect mcp_search_server.py

# Run test script
python test_mcp_search.py

🔒 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:

Enhanced Analysis: Better MCP detection algorithms
Caching: Add result caching for performance
Filtering: Additional filtering options
Exports: Export capabilities for found MCPs
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:

python test_mcp_search.py

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

🆘 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! 🚀

MCP Search Server - Comprehensive Documentation 🚀

🎥 Demo

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

🎬 View Demo on YouTube

Demo
Features
Architecture
Quick Start
Installation Guide
Usage Guide
Configuration
API Reference
Integration
Troubleshooting
Contributing
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

ExaSearchClient: Handles interaction with Exa's search, answer, and find-similar APIs
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
MCPRecommendation: Data structure representing discovered MCPs with:
- Name, description, and URLs
- Repository information
- Confidence scores
- Key features and categories
- Installation notes

Available Tools

Tool	Description	Use Case
`search_mcps`	Search for MCPs based on requirements	"I need an MCP for database access"
`get_mcp_details`	Get detailed info about a specific MCP	Analyze a specific GitHub repo
`find_similar_mcps`	Find MCPs similar to a reference	Discover alternatives to known MCPs
`ask_mcp_question`	Ask specific questions about MCPs	"What are the best MCPs for web scraping?"
`categorize_mcps`	Get MCPs organized by categories	Explore MCPs by functional area

🚀 Quick Start

Prerequisites

Python 3.10+
Exa API Key - Get one from Exa Dashboard

Installation

Clone and setup:

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

Set your Exa API key:
```
export EXA_API_KEY=your_api_key_here
```
Run the server:
```
python mcp_search_server.py
```

Testing with FastMCP CLI

# Test the server interactively
fastmcp dev mcp_search_server.py

# Or inspect with web UI
fastmcp inspect mcp_search_server.py

📦 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)

Open Microsoft Store
Search for "Python 3.11" or "Python 3.12"
Click "Get" to install
Verify installation: python --version

Option 2: Python.org

Visit python.org/downloads
Download latest Python 3.10+ for Windows
Run installer with "Add to PATH" checked
Verify: python --version

Option 3: Chocolatey

# Install Chocolatey first (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Python
choco install python

macOS

Option 1: Homebrew (Recommended)

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.11

Option 2: Python.org

Visit python.org/downloads
Download latest Python 3.10+ for macOS
Run the installer
Verify: python3 --version

Linux (Ubuntu/Debian)

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-pip python3.11-venv

# Verify installation
python3.11 --version

Linux (CentOS/RHEL/Fedora)

# Fedora
sudo dnf install python311 python311-pip

# CentOS/RHEL (with EPEL)
sudo yum install python311 python311-pip

🚀 MCP Search Server Installation

Method 1: Direct Download and Setup

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

Install dependencies:

# Using pip
pip install -r requirements.txt

# Or install manually
pip install fastmcp>=2.0.0 httpx>=0.25.0

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)

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

Install dependencies:
```
pip install -r requirements.txt
```
Run server:
```
python mcp_search_server.py
```

🔑 Exa API Key Setup

1. Get API Key

Visit Exa Dashboard
Sign up or log in
Navigate to API Keys section
Create a new API key
Copy the key (starts with exa_)

2. Set Environment Variable

Temporary (Current Session)

# Linux/Mac
export EXA_API_KEY=exa_your_key_here

# Windows Command Prompt
set EXA_API_KEY=exa_your_key_here

# Windows PowerShell
$env:EXA_API_KEY="exa_your_key_here"

Permanent Setup

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

echo 'export EXA_API_KEY=exa_your_key_here' >> ~/.bashrc
source ~/.bashrc

Windows (System Environment Variables):

Open "Environment Variables" in Control Panel
Add new User Variable:
- Name: EXA_API_KEY
- Value: exa_your_key_here
Restart terminal/applications

✅ Verification and Testing

1. Basic Installation Test

# Test Python installation
python --version

# Test package imports
python -c "import fastmcp, httpx; print('Dependencies OK')"

2. API Key Test

# Test environment variable
python -c "import os; print('API Key:', 'Set' if os.getenv('EXA_API_KEY') else 'Not Set')"

3. Server Test

# Run test script
python test_mcp_search.py

# Or run server directly
python mcp_search_server.py

📚 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

Locate Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

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"
      }
    }
  }
}

Restart Claude Desktop
Test in Claude:
- Type: "Search for database MCP servers"
- Claude should now be able to use the MCP search tools

Method 2: Cursor Integration

Open Cursor settings
Navigate to MCP configuration

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

# Interactive testing with FastMCP CLI
fastmcp dev mcp_search_server.py

# Web-based inspector
fastmcp inspect mcp_search_server.py

Method 4: Programmatic Usage

import asyncio
import json
from fastmcp import Client

async def search_for_mcps():
    async with Client("mcp_search_server.py") as client:
        # Search for MCPs
        result = await client.call_tool("search_mcps", {
            "requirement": "database access",
            "max_results": 5
        })
        
        data = json.loads(result.text)
        print(f"Found {data['total_found']} MCPs")
        
        for rec in data['recommendations']:
            print(f"- {rec['name']}: {rec['description']}")

# Run the search
asyncio.run(search_for_mcps())

🎯 Common Use Cases

Use Case 1: Finding MCPs for Specific Tasks

Goal: Find MCPs for database operations

Steps:

Use the search_mcps tool
Provide requirement: "database access and SQL operations"
Review confidence scores and categories
Get detailed info with get_mcp_details

Example interaction:

User: "I need an MCP for SQLite database access"
Tool: search_mcps(requirement="SQLite database access", max_results=5)
Result: List of SQLite-related MCPs with confidence scores

Use Case 2: Exploring MCP Categories

Goal: Understand what MCPs are available in different areas

Steps:

Use categorize_mcps tool
Provide broad requirement like "file management"
Explore different categories returned
Drill down into specific categories

Example interaction:

User: "What file management MCPs are available?"
Tool: categorize_mcps(requirement="file management")
Result: MCPs grouped by categories (File System, Cloud Storage, etc.)

Use Case 3: Research and Comparison

Goal: Compare similar MCPs

Steps:

Find initial MCP with search_mcps
Use find_similar_mcps to find alternatives
Use get_mcp_details for detailed comparison
Ask specific questions with ask_mcp_question

Example interaction:

User: "Find alternatives to the FastMCP file server"
Tool: find_similar_mcps(reference_mcp_url="https://github.com/example/fastmcp-file")
Result: List of similar MCPs with comparison data

Use Case 4: General Questions

Goal: Get expert answers about MCPs

Steps:

Use ask_mcp_question tool
Ask specific questions about MCP ecosystem
Get answers with citations
Follow up with more specific searches

Example interaction:

User: "What are the most popular MCPs for web scraping?"
Tool: ask_mcp_question(question="most popular MCPs for web scraping")
Result: Direct answer with citations and source links

📋 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

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:

# STDIO (default) - for local use
mcp.run()

# HTTP Streaming - for web deployment
mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

# SSE - for compatibility
mcp.run(transport="sse", host="127.0.0.1", port=8000)

📊 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:

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

With Cursor

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

Programmatic Access

from fastmcp import Client

async def main():
    async with Client("mcp_search_server.py") as client:
        result = await client.call_tool("search_mcps", {
            "requirement": "file management",
            "max_results": 5
        })
        print(result.text)

🚨 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:

# Install missing dependencies
pip install fastmcp httpx

# Or reinstall from requirements
pip install -r requirements.txt

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:

# Use --user flag
pip install --user -r requirements.txt

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate    # Windows
pip install -r requirements.txt

Issue: "SSL Certificate verify failed"

Solutions:

# Upgrade certificates
pip install --upgrade certifi

# Or use --trusted-host (temporary fix)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org fastmcp

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:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS Permission Issues

If you get permission errors:

# Use Homebrew Python instead of system Python
brew install python@3.11
export PATH="/opt/homebrew/bin:$PATH"

Linux Missing Development Headers

If compilation fails:

# Ubuntu/Debian
sudo apt install python3-dev build-essential

# CentOS/RHEL
sudo yum install python3-devel gcc

Performance Tips

Use specific requirements for better results
Start with broader searches then narrow down
Check confidence scores to gauge relevance
Use GitHub-only search for higher quality results
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:

Content Analysis: Scans for MCP-specific keywords and indicators
Source Credibility: Prioritizes GitHub repositories and official documentation
Exa Scoring: Leverages Exa's semantic understanding
Feature Extraction: Automatically identifies key capabilities
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:

# Interactive testing
fastmcp dev mcp_search_server.py

# Web-based inspector
fastmcp inspect mcp_search_server.py

# Run test script
python test_mcp_search.py

🔒 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:

Enhanced Analysis: Better MCP detection algorithms
Caching: Add result caching for performance
Filtering: Additional filtering options
Exports: Export capabilities for found MCPs
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:

python test_mcp_search.py

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

🆘 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! 🚀

MCP Search Server

MCP Search Server - Comprehensive Documentation 🚀

🎥 Demo

Table of Contents

🌟 Features

🏗️ Architecture

Core Components

Available Tools

🚀 Quick Start

Prerequisites

Installation

Testing with FastMCP CLI

📦 Installation Guide

📋 Prerequisites

Required:

Optional:

🐍 Python Installation

Windows

macOS

Linux (Ubuntu/Debian)

Linux (CentOS/RHEL/Fedora)

🚀 MCP Search Server Installation

Method 1: Direct Download and Setup

Method 2: Using Virtual Environment (Recommended)

🔑 Exa API Key Setup

1. Get API Key

2. Set Environment Variable

✅ Verification and Testing

1. Basic Installation Test

2. API Key Test

3. Server Test

📚 Usage Guide

🛠️ Integration Methods

Method 1: Claude Desktop Integration

Method 2: Cursor Integration

Method 3: Command Line Testing

Method 4: Programmatic Usage

🎯 Common Use Cases

Use Case 1: Finding MCPs for Specific Tasks

Use Case 2: Exploring MCP Categories

Use Case 3: Research and Comparison

Use Case 4: General Questions

📋 Available Tools Reference

1. search_mcps

2. get_mcp_details

3. find_similar_mcps

4. ask_mcp_question

5. categorize_mcps

🔍 Understanding Results

Confidence Scores

Categories

Key Features

🔧 Configuration

Environment Variables

Server Configuration

📊 API Reference

Tool Parameters

search_mcps

get_mcp_details

find_similar_mcps

ask_mcp_question

categorize_mcps

Response Format

🛠️ Integration

With Claude Desktop

With Cursor

Programmatic Access

🚨 Troubleshooting

Common Issues

Issue: "python: command not found"

Issue: "No module named 'fastmcp'"

Issue: "EXA_API_KEY environment variable is required"

Issue: Permission errors during installation

Issue: "SSL Certificate verify failed"

Issue: "Error searching for MCPs: HTTP 401"

Issue: "No MCPs found for requirement"

Issue: Tool returns empty results

Platform-Specific Issues

Windows PowerShell Execution Policy

macOS Permission Issues

1. `search_mcps`

2. `get_mcp_details`

3. `find_similar_mcps`

4. `ask_mcp_question`

5. `categorize_mcps`

`search_mcps`

`get_mcp_details`

`find_similar_mcps`

`ask_mcp_question`

`categorize_mcps`