🚀 SuperMCP - Universal MCP Server Discovery

The meta-MCP that finds MCPs for you

SuperMCP is a Model Context Protocol (MCP) server that dynamically discovers and recommends the best free MCP servers for any task by searching multiple MCP marketplaces in real-time. Built for the PromptWars Hackathon at Scaler School of Technology, Hyderabad.

🌟 Features

Feature	Description
🔍 Dynamic Discovery	Searches across 4 major MCP marketplaces simultaneously
📊 Smart Ranking	Intelligent scoring algorithm with weighted criteria
⚡ Fast Parallel Fetching	Async queries for sub-second results
🤖 AI-Ready	Simple MCP tool interface for Claude & other AI assistants
🎯 100% Dynamic	No hardcoded keywords - works with ANY search term
💎 Free Tier Focus	Automatically filters and prioritizes free MCP servers
🌉 MCP Gateway	Dynamically load and proxy other MCP servers on-the-fly

Marketplaces Searched

🛍️ mcpmarket.com - Community marketplace for MCP servers
🔧 mcp.so - MCP server directory
📦 mcpserverfinder.com - MCP server discovery platform
🗄️ mcp-archive.com - MCP server archive

🚀 Installation

Prerequisites

Python 3.10 or higher
uv package manager (recommended)

Quick Install with uv (Recommended)

# Clone or navigate to SuperMCP directory
cd SUPERMCP

# Install dependencies and create virtual environment
uv sync

# Verify installation
uv run python -c "import supermcp; print('✅ SuperMCP Ready!')"

Quick Install with pip (Alternative)

# Clone or navigate to SuperMCP directory
cd SUPERMCP

# Install dependencies
python -m pip install -e .

# Verify installation
python -c "import supermcp; print('✅ SuperMCP Ready!')"

📖 Usage

Running the Server

With uv (Recommended)

# Run using uv
uv run supermcp

With uvx (Global Command)

# Install and run globally via uvx
uvx supermcp

With Python (Fallback)

# Direct Python execution
python -m supermcp
# or
python src/supermcp/server.py

You should see a message indicating the server has started and is monitoring marketplaces.

Integrating with Claude Desktop

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

Option A: Using uv (Recommended)

{
  "mcpServers": {
    "supermcp": {
      "command": "uv",
      "args": ["run", "supermcp"],
      "cwd": "/path/to/SUPERMCP",
      "env": {
        "PYTHONPATH": "/home/anonymouslokesh/Desktop/SUPERMCP/src"
      }
    }
  }
}

Option B: Using uvx (Global)

{
  "mcpServers": {
    "supermcp": {
      "command": "uvx",
      "args": ["supermcp"],
      "cwd": "/path/to/SUPERMCP"
    }
  }
}

Option C: Using Python (Fallback)

{
  "mcpServers": {
    "supermcp": {
      "command": "python",
      "args": ["-m", "supermcp"],
      "cwd": "/path/to/SUPERMCP",
      "env": {
        "PYTHONPATH": "/home/anonymouslokesh/Desktop/SUPERMCP/src"
      }
    }
  }
}

Restart Claude Desktop

Ask Claude:

"Find me the best MCP server for websearch"
"I need an MCP server for GitHub integration"
"What's the best database MCP server?"

🛠️ Available Tools

`fetch_mcp`

Discovers the best free MCP server for any task or functionality.

Parameters:

Parameter	Type	Required	Description
`keyword`	string	✅	Task or functionality (e.g., "websearch", "github", "slack")

Returns:

{
  "query": "websearch",
  "marketplaces_searched": 4,
  "total_results": 12,
  "best_server": {
    "name": "websearch-mcp",
    "description": "Advanced web search with multiple engines",
    "url": "https://github.com/user/websearch-mcp",
    "repository_url": "https://github.com/user/websearch-mcp",
    "install_command": "npm install -g websearch-mcp",
    "provider": "MCPMarket",
    "tags": ["search", "web", "google"],
    "score": 89.5
  },
  "alternatives": [
    {
      "name": "search-tools-mcp",
      "score": 76.2,
      ...
    }
  ]
}

`list_providers`

Return a list of configured providers (adapters) and their base URLs.

Example:

{
  "providers": [
    {"name": "MCPMarket", "base_url": "https://mcpmarket.com"},
    ...
  ],
  "total": 4
}

`search_marketplace`

Search a specific marketplace (by provider name) for a keyword.

Parameters: marketplace (string), keyword (string)

Example:

{
  "query": "websearch",
  "marketplaces_searched": 1,
  "total_results": 1,
  "best_server": { ... }
}

`get_server_info`

Given a server url, attempt to return metadata about that server.

Parameters: url (string)

`ping`

A simple health check tool that returns basic status and the package version.

{"status": "ok", "version": "0.1.0"}

`explain_best_server`

Return the best server for a given keyword with a scoring breakdown.

Parameters: keyword (string)

Example:

{
  "best_server": { ... },
  "breakdown": {
    "parts": { ... },
    "weighted": { ... },
    "total": 85.6
  }
}

Resources

The server exposes helper resources that clients can read:

config://version - returns the server version string
providers://list - returns a list of configured providers

`list_marketplaces`

Returns all MCP marketplaces that SuperMCP searches.

Returns:

{
  "marketplaces": [
    {
      "name": "MCPMarket",
      "url": "https://mcpmarket.com",
      "description": "Community marketplace for MCP servers"
    },
    ...
  ],
  "total": 4
}

🌉 MCP Gateway — Use Other MCPs On-The-Fly

SuperMCP isn't just a discovery tool — it's a meta-MCP gateway that can dynamically load and proxy other MCP servers. An AI agent using SuperMCP can self-discover, connect to, and use any MCP server's tools in a single session.

Quick Start

Agent: "I need to search the web"
→ auto_discover_mcp("websearch")     # finds + loads best websearch MCP
→ call_mcp_tool("websearch", "search", {"query": "hello world"})

Gateway Tools

Tool	Description
`load_mcp`	Connect to an MCP server (by config name or inline command/args)
`list_loaded_mcps`	Show all currently connected MCP servers
`list_mcp_tools`	List tools available from a loaded MCP server
`call_mcp_tool`	Invoke a tool on a loaded MCP server
`unload_mcp`	Disconnect a loaded MCP server
`auto_discover_mcp`	Search → auto-load best match → return tools (all-in-one)

Config File (`mcp_servers.json`)

Pre-configure known MCP servers (same format as Claude Desktop):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      "transport": "stdio"
    }
  },
  "defaults": {
    "idle_timeout_seconds": 300
  }
}

Then load by name: load_mcp("filesystem")

Workflow

graph LR
    A[fetch_mcp] -->|discover| B[load_mcp]
    B -->|connect| C[list_mcp_tools]
    C -->|inspect| D[call_mcp_tool]
    D -->|done| E[unload_mcp]
    F[auto_discover_mcp] -->|all-in-one| D

🏗️ Architecture

SUPERMCP/
├── src/supermcp/
│   ├── server.py                 # FastMCP server entry point
│   ├── core/
│   │   ├── types.py             # Pydantic models (MCPServer, SearchResponse)
│   │   └── config.py            # Configuration (URLs, weights, timeouts)
│   ├── providers/               # Marketplace adapters
│   │   ├── base.py             # Abstract MarketplaceAdapter class
│   │   ├── mcpmarket.py        # mcpmarket.com scraper
│   │   ├── mcpso.py            # mcp.so scraper
│   │   ├── mcpserverfinder.py  # mcpserverfinder.com scraper
│   │   └── mcparchive.py       # mcp-archive.com scraper
│   ├── services/
│   │   ├── aggregator.py       # Parallel marketplace fetching
│   │   └── scorer.py           # Relevance scoring algorithm
│   └── gateway/                 # 🆕 MCP Gateway
│       ├── config.py           # Server config models & JSON loader
│       └── manager.py          # Connection lifecycle & tool proxying
├── mcp_servers.json             # Gateway config (pre-configured MCPs)
├── tests/
├── pyproject.toml
└── README.md

⚙️ How It Works

1. Query Reception

AI assistant calls fetch_mcp tool with a keyword (e.g., "websearch")

2. Parallel Marketplace Search

SuperMCP simultaneously queries all 4 marketplaces:

tasks = [adapter.search(keyword) for adapter in self.adapters]
results = await asyncio.gather(*tasks)

3. HTML Parsing

Each marketplace adapter:

Builds dynamic search URL with keyword
Fetches HTML via httpx
Parses with BeautifulSoup
Extracts: name, description, URL, repository, install command, tags

4. Filtering & Scoring

# Filter free servers
free_servers = [s for s in all_servers if s.is_free]

# Score based on weighted criteria
score = (
    keyword_match * 40% +
    has_install_cmd * 20% +
    has_repo * 15% +
    description_quality * 15% +
    tag_match * 10%
)

5. Deduplication & Ranking

Remove duplicates (same name)
Sort by score descending
Return best + alternatives

6. Response

AI receives structured response with best match and alternatives

📊 Scoring Algorithm

SuperMCP uses a weighted scoring system (0-100):

Factor	Weight	Description
Keyword Match	40%	Presence in name (80pts) or description (20pts)
Install Command	20%	Availability of installation instructions
Repository URL	15%	Link to source code repository
Description Quality	15%	Length and completeness of description
Tag Match	10%	Relevance of tags to keyword

Example:

websearch-mcp searching for "websearch"
- Keyword in name: 80pts × 40% = 32
- Has install command: 100pts × 20% = 20
- Has repository: 100pts × 15% = 15
- Good description (150 chars): 100pts × 15% = 15
- Tag match: 0pts × 10% = 0
- Total: 82/100

🧪 Testing

Validate Installation

uv run python -c "import supermcp; print('✅ OK')"

Run Demo (Offline)

python demo.py

Test Live Search (Hits Real URLs)

python test_supermcp.py

Note: Live testing will actually fetch from marketplaces. Use sparingly to avoid rate limits.

Run Test Suite

uv run pytest tests/ -v

All 24 tests passing! ✅

⚙️ Configuration

Edit src/core/config.py to customize:

class Config:
    # Timeout for HTTP requests (seconds)
    REQUEST_TIMEOUT = 10
    
    # Maximum concurrent requests
    MAX_CONCURRENT_REQUESTS = 4
    
    # User agent for web scraping
    USER_AGENT = "Mozilla/5.0 (...)"
    
    # Marketplace URLs (uses {keyword} placeholder)
    MARKETPLACES = {
        "mcpmarket": "https://mcpmarket.com/search?q={}",
        ...
    }
    
    # Scoring weights (must sum to 100)
    SCORE_WEIGHTS = {
        "keyword_match": 40.0,
        "has_install_cmd": 20.0,
        ...
    }

🐛 Troubleshooting

Import Errors

# Ensure you're using absolute imports
uv run python validate_imports.py

Marketplace Parsing Failures

HTML structure may have changed
Check src/providers/*.py and update CSS selectors
Enable debug logging in adapters

No Results Found

Try different/simpler keywords
Check if marketplaces are accessible
Verify network connectivity

Claude Desktop Integration Issues

Verify config path is correct (use absolute paths)
Check Python is in system PATH
Restart Claude Desktop after config changes
Check Claude logs: %APPDATA%\Claude\logs

🚀 Future Enhancements

🤝 Contributing

Contributions welcome! Areas to improve:

New Marketplace Adapters: Add support for more MCP directories
Better Parsing: Improve HTML extraction logic
Scoring Refinement: Enhance relevance algorithm
Testing: Add unit tests for adapters and scoring
Documentation: Improve examples and guides

📄 License

MIT License - feel free to use, modify, and distribute.

🙏 Acknowledgments

Built with FastMCP by Marvin
Inspired by the growing MCP ecosystem
Thanks to all MCP marketplace maintainers
Developed for PromptWars Hackathon at Scaler School of Technology, Hyderabad

Made with care for the MCP community

Report Bug · Request Feature

Name		Name	Last commit message	Last commit date
src/supermcp		src/supermcp
tests		tests
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
test.py		test.py
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

🚀 SuperMCP - Universal MCP Server Discovery

🌟 Features

Marketplaces Searched

🚀 Installation

Prerequisites

Quick Install with uv (Recommended)

Quick Install with pip (Alternative)

📖 Usage

Running the Server

With uv (Recommended)

With uvx (Global Command)

With Python (Fallback)

Integrating with Claude Desktop

Option A: Using uv (Recommended)

Option B: Using uvx (Global)

Option C: Using Python (Fallback)

🛠️ Available Tools

fetch_mcp

list_providers

search_marketplace

get_server_info

ping

explain_best_server

Resources

list_marketplaces

🌉 MCP Gateway — Use Other MCPs On-The-Fly

Quick Start

Gateway Tools

Config File (mcp_servers.json)

Workflow

🏗️ Architecture

⚙️ How It Works

1. Query Reception

2. Parallel Marketplace Search

3. HTML Parsing

4. Filtering & Scoring

5. Deduplication & Ranking

6. Response

📊 Scoring Algorithm

🧪 Testing

Validate Installation

Run Demo (Offline)

Test Live Search (Hits Real URLs)

Run Test Suite

⚙️ Configuration

🐛 Troubleshooting

Import Errors

Marketplace Parsing Failures

No Results Found

Claude Desktop Integration Issues

🚀 Future Enhancements

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`fetch_mcp`

`list_providers`

`search_marketplace`

`get_server_info`

`ping`

`explain_best_server`

`list_marketplaces`

Config File (`mcp_servers.json`)