MCP Scout

A simple MCP discovery and installation engine designed to be orchestrated by Claude Code.

MCP Scout provides atomic operations for searching, installing, and managing MCPs without making assumptions about tools or workflows. All intelligence and preferences are handled by Claude Code.

What This Does

MCP Scout is basically a search engine for MCPs (Model Context Protocol servers). Instead of trying to be smart about what you want, it just gives you raw search results from the Smithery Registry and lets you (or Claude) decide what to do with them.

Getting Started

What You Need

• Python 3.10 or higher (FastMCP requires Python 3.10+)
• A Smithery API key (grab one at smithery.ai)
• Claude CLI installed

First, check your Python version:

python --version  # Should show 3.10+ 
# If that doesn't work, try: python3 --version

The Easy Way (Two Steps)

⚠️ Important: The Claude CLI doesn't remember environment variables between sessions, so you'll need to add your API key manually.

1. Install ScoutMCP:

claude mcp add ScoutMCP -- python /path/to/ScoutMCP/server.py

2. Add your API key: Open your Claude config file (~/.config/claude/claude_config.json) and find the ScoutMCP entry. Add your API key like this:

{
  "mcpServers": {
    "ScoutMCP": {
      "type": "stdio",
      "command": "python", 
      "args": ["/path/to/ScoutMCP/server.py"],
      "env": {
        "SMITHERY_API_KEY": "your_smithery_api_key_here"
      }
    }
  }
}

3. Restart Claude to pick up the new config.

Alternative Ways to Install

Option A: Wrapper Script (Easiest)

Create a simple script that includes your API key:

1. Create scout_wrapper.sh:

#!/bin/bash
export SMITHERY_API_KEY="your_smithery_api_key_here"
python /path/to/ScoutMCP/server.py

2. Make it runnable and install:

chmod +x scout_wrapper.sh
claude mcp add ScoutMCP -- ./scout_wrapper.sh

Option B: System Environment Variable

Add this to your shell profile (~/.zshrc or ~/.bashrc):

export SMITHERY_API_KEY="your_smithery_api_key_here"

Then restart your terminal and install normally:

claude mcp add ScoutMCP -- python /path/to/ScoutMCP/server.py

Manual Installation

# Clone the repo
git clone https://github.com/yudduy/ScoutMCP.git
cd mcp-scout

# Install Python dependencies (make sure you're using Python 3.10+)
pip install -r requirements.txt

# Install ScoutMCP
claude mcp add ScoutMCP -- python /full/path/to/server.py

# Then manually add API key to Claude config as shown above

When Things Go Wrong

"ModuleNotFoundError: No module named 'fastmcp'"

This usually means FastMCP isn't installed or you're using the wrong Python version.

First, check your Python version:

python --version  # Must be 3.10+

If that's not the issue, try installing with the right Python:

# Find your Python 3.10+ installation
which python3.10  # or python3.11, python3.12, etc.

# Install dependencies with the correct Python
/path/to/python3.10 -m pip install -r requirements.txt

# Update your Claude config to use the right Python path

If you have Anaconda:

# Install with Anaconda Python
/opt/anaconda3/bin/pip install -r requirements.txt

# Update Claude config to use Anaconda Python
"command": "/opt/anaconda3/bin/python"

"Failed to connect" Error

This almost always means your API key isn't set up right.

Check your config: Look at your ~/.config/claude/claude_config.json file and make sure it has:

{
  "mcpServers": {
    "ScoutMCP": {
      "env": {
        "SMITHERY_API_KEY": "your_actual_key_here"
      }
    }
  }
}

Test the server manually:

export SMITHERY_API_KEY="your_key"
python /path/to/server.py

You should see the FastMCP startup screen without any errors.

Check the server path: Make sure the path in your Claude config actually points to the server.py file:

ls -la /path/to/ScoutMCP/server.py  # Should exist

Python Path Issues

Find the right Python:

# Check all Python versions on your system
ls -la /usr/bin/python*
ls -la /opt/anaconda3/bin/python*

# Test which one has fastmcp installed
/path/to/python -c "import fastmcp; print('FastMCP available')"

Update your Claude config with the right path:

{
  "mcpServers": {
    "ScoutMCP": {
      "command": "/correct/path/to/python",
      "args": ["/path/to/server.py"]
    }
  }
}

Environment Variables

• SMITHERY_API_KEY: Your Smithery Registry API key (required)

The Tools

Search Tools

search_registry

Pure semantic search of the Smithery Registry. No interpretation, just raw results.

Parameters:

• query (string): Your exact search term
• limit (int, optional): Max results to return (default: 10)
• filters (dict, optional): Smithery API filters (is_deployed, is_verified, owner, etc.)

Returns:

• Raw search results from Smithery with status and results array

get_mcp_info

Get the full details about a specific MCP.

Parameters:

• qualified_name (string): The exact MCP identifier

Returns:

• Complete MCP details including connections and deployment info

Installation Tools

install_mcp

Install a single MCP.

Parameters:

• qualified_name (string): MCP to install
• install_command (string, optional): Override the install command
• timeout_seconds (int, optional): How long to wait for installation (default: 60)

Returns:

• Installation status and output

verify_installation

Check if an MCP is properly installed and working.

Parameters:

• qualified_name (string): MCP to verify

Returns:

• Verification status and config path

Management Tools

list_installed

Show all the MCPs currently installed in your Claude config.

Returns:

• List of installed MCPs with their configurations

uninstall_mcp

Remove an MCP from your Claude configuration.

Parameters:

• qualified_name (string): MCP to remove

Returns:

• Removal status

Old Tools (Don't Use These)

setup_mcp ⚠️ DEPRECATED

Simple wrapper around the atomic tools. Use search_registry, install_mcp, verify_installation instead.

discover_mcps ⚠️ DEPRECATED

Old discovery tool. Use search_registry for direct semantic search instead.

How to Use It

Basic Workflow

1. Search for MCPs

# Simple search
search_registry("testing tools")

# Search with filters
search_registry("database", filters={"is_deployed": True})

# Specific search
search_registry("react development")

2. Install an MCP

# Search first
results = search_registry("python linter", limit=1)
if results["status"] == "success" and results["results"]:
    qualified_name = results["results"][0]["qualified_name"]
    
    # Install it
    install_mcp(qualified_name)
    
    # Make sure it worked
    verify_installation(qualified_name)

3. Manage Your MCPs

# See what's installed
list_installed()

# Remove something you don't want
uninstall_mcp("some-mcp-name")

Real-World Examples

Example 1: Finding Testing Tools for a React Project

# Step 1: Claude Code figures out what to search for based on what you asked
user_request = "I need testing tools for my React TypeScript project"

# Step 2: Search with specific queries
search_results = []
for query in ["react testing", "typescript test", "component testing"]:
    result = search_registry(query, limit=3)
    search_results.append(result)

# Step 3: Claude Code looks at the results and shows you options
# Step 4: You pick what you want
# Step 5: Claude Code installs it for you
install_mcp("selected-mcp-qualified-name")

Example 2: Finding Database Tools

# Claude Code understands what you need and searches appropriately
queries = [
    "postgresql client",
    "database management", 
    "sql tools"
]

for query in queries:
    results = search_registry(query, limit=2, filters={"is_verified": True})
    # Claude Code processes the results and makes recommendations

Search by Concept, Not Just Names

Instead of looking for specific tool names, search for what you want to do:

• "code quality" → Finds linters, formatters, static analysis tools
• "web scraping" → Finds web crawling and data extraction tools
• "file operations" → Finds file system and file manipulation tools
• "api testing" → Finds HTTP clients, API testing frameworks
• "data processing" → Finds ETL, analytics, and data transformation tools

Handling Errors

# Search with error handling
result = search_registry("nonexistent tool")
if result["status"] == "error":
    print(f"Search failed: {result['message']}")
    # Claude Code can try different search terms

# Installation with error handling  
install_result = install_mcp("some-mcp")
if install_result["status"] == "error":
    error_code = install_result["error_code"]
    if error_code == "INSTALL_TIMEOUT":
        # Try again with more time
        install_mcp("some-mcp", timeout_seconds=120)

Moving from the Old Tools

# Old way (don't use this anymore)
setup_mcp(query="python linter")  # This will give you a deprecation warning

# New way (use this instead)
results = search_registry("python linter", limit=3)
# Claude Code looks at the options and your preferences
install_mcp(selected_qualified_name)
verify_installation(selected_qualified_name)

Working with Claude Code

For the best experience with Claude Code and getting good MCP recommendations, check out the complete prompt guide in PROMPT.md.

License

MIT