MCP Server Marketplace#

Help users discover, install, configure, and manage MCP servers. Supports OpenClaw, Claude Desktop, Claude Code, and Cursor.

Core Principles#

1. ClawHub First — Always check for a ClawHub plugin bundle before raw server install. Bundles include skills and workflows on top of the MCP connection.
2. Never Store Secrets — Auth values are always env var references ( ${VAR_NAME}), never raw tokens. Never ask the user to paste their actual token in chat.
3. Verify Before Acting — Confirm server choice and auth readiness before installing.
4. Guide Completely — Don't just install. Walk through auth setup and verification.

Intent Routing#

Classify the user's request into one of these intents, then follow the corresponding workflow.

DISCOVER — "What MCP servers are available for X?"#

1. Run search: text

   python3 {baseDir}/scripts/search_registries.py --query "<user's topic>" [--category "<category>"]
   
   

2. If clawHubMatch is present, mention the bundle first: "There's a [bundle name] plugin on ClawHub with [N] skills — want that instead?"

3. Present results as a numbered list with name, description, and auth requirements.

4. If any result has "source": "npm" or "source": "smithery", add a note: "This server is from [npm/Smithery] and hasn't been verified by our team. It should work but proceed with caution."

5. Offer to install any result.

6. If user asks "what else should I install?" or "recommend more servers": text

   python3 {baseDir}/scripts/smart_recommend.py [--max-results 5]
   
   

   Present recommendations with their reasons (which installed servers they complement). Offer to install any.

INSTALL — "Install the X MCP server"#

This is the most complex flow. Follow all steps in order.

Step 1 — Search:

text

python3 {baseDir}/scripts/search_registries.py --query "<server name>"

Step 2 — ClawHub bundle offer: If clawHubMatch is present, offer the bundle:

I found a [bundle displayName] plugin on ClawHub that includes the MCP connection plus [skillCount] additional skills. Would you like the full bundle, or just the raw MCP connection?

If user wants the bundle, guide them to install via ClawHub ( clawhub install <bundleId>). Then record the install and stop.

Step 3 — Confirm server: If multiple results, present a numbered list and ask user to pick. If one result, confirm: "I'll set up [displayName] — sound good?"

Step 3.5 — Compatibility check (if non-default client): If the user specified a client or you detected a non-OpenClaw client, check compatibility:

text

python3 {baseDir}/scripts/check_compatibility.py --server-id "<id>" --client "<client>"

If compatible is false, warn the user and suggest alternatives. If there are warnings, mention them but proceed.

Step 4 — Build config:

text

python3 {baseDir}/scripts/build_config.py --server-id "<id>" [--client "<client>"]

The --client flag is optional. If omitted, the script auto-detects the client (OpenClaw, Claude Desktop, Claude Code, or Cursor). The output includes mergeTarget (the config file path) and client (the detected client name).

Step 5 — Auth guidance (if server has requiredEnv): Follow the Auth Guidance Pattern below. Wait for user to confirm they have their token ready before proceeding.

Step 6 — Check prerequisites and install:

text

python3 {baseDir}/scripts/install_server.py --server-id "<id>"

This script checks prerequisites and returns the install command — it does NOT run it.

• If prerequisitesMet is false, show the prerequisites.suggestion and help the user install the prerequisite first.
• If prerequisitesMet is true, run the installCommand.command directly using the Bash tool. For example, if the output says "command": "npx -y @github/mcp-server --help", run that command to verify the package resolves.
• If installCommand.command is null (HTTP servers), skip — no install needed.
• If the install command fails, try the installCommand.fallbackCommand if present, or consult {baseDir}/references/troubleshooting.md.

Step 7 — Write config: Present the configEntry from step 4 and explain it needs to be added to the config file at mergeTarget (the path returned by build_config.py). If the config file exists, merge the new server entry into the existing mcpServers object. If it doesn't exist, create it:

json

{
  "mcpServers": {
    <configEntry content here>
  }
}

Step 8 — Record state:

text

python3 {baseDir}/scripts/manage_servers.py --action record --server-id "<id>" --package "<package>" --transport "<transport>" --install-method "<method>" --source "<source>"

Use --source curated, --source npm, or --source smithery based on where the server was found.

Step 8.5 — Health check (optional):

text

python3 {baseDir}/scripts/health_check.py --server-id "<id>"

If status is "healthy", include the tool count in the summary. If "unhealthy" or "error", troubleshoot before declaring success — consult {baseDir}/references/troubleshooting.md.

Step 9 — Summary: Tell the user what was installed, what tools are now available (from health check if run), and remind them to restart their client to pick up the new server.

BULK INSTALL — "Install the dev toolkit" / "Set up servers for data work"#

1. If user mentions a specific bundle, resolve it. If they describe a use case, match to the closest bundle: text

   python3 {baseDir}/scripts/bulk_install.py --bundle "<bundle-name>"
   
   

   Available bundles: standard-dev, data-engineering, web-frontend, devops, productivity, ai-ml.

2. If unsure which bundle, list them all: text

   python3 {baseDir}/scripts/bulk_install.py --bundle __list__
   
   

   Present the options and let the user choose.

3. Present the install plan: show which servers will be installed and which are already configured.

4. For each server in toInstall, follow the INSTALL workflow (Steps 3-9). Process them one at a time, confirming auth requirements for each.

5. After all servers are installed, present a summary: "Installed X servers, Y were already configured."

DETECT — "Scan for MCP servers" / "What MCP servers do I already have installed?"#

1. Run detection: text

   python3 {baseDir}/scripts/detect_servers.py --verbose
   
   

2. If unconfigured has entries: "I found [count] MCP server packages on your system that aren't configured yet: [list them]. Want me to set up any of them?"

3. If alreadyConfigured has entries: mention them as already active.

4. If nothing detected: "No known MCP server packages found. Want me to search for servers to install?"

5. For each server the user wants to configure, follow the INSTALL workflow starting at Step 4 (Build config) — the package is already installed.

RECOMMEND — "Set up MCP for this project" / "What servers should I use?"#

1. Scan the project: text

   python3 {baseDir}/scripts/recommend_servers.py [--project-dir "<path>"]
   
   

   If the user specifies a project type: python3 {baseDir}/scripts/recommend_servers.py --template "<type>" Available templates: python-web, node-fullstack, data-science, mobile, devops, static-site.

2. If detected is true:

   • Present the detected template: "This looks like a [displayName] project (matched [files/patterns])."
   • List recommended servers first, then optional servers.
   • Mark any that are already configured.
   • Offer to install the recommended set (routes to BULK INSTALL logic).

3. If detected is false:

   • List available templates and ask the user to pick one.
   • Or suggest running DISCOVER for a broader search.

CONFIGURE — "Set the API key for X" / "Connect X to my database"#

1. Identify the server from the user's request.

2. Run build_config.py --server-id "<id>" with any custom env/args the user provides: text

   python3 {baseDir}/scripts/build_config.py --server-id "<id>" --custom-env '{"KEY": "${KEY}"}'
   
   

3. Follow the Auth Guidance Pattern for any new env vars.

4. Update the .mcp.json config entry.

STATUS — "Show my installed MCP servers"#

1. Run: text

   python3 {baseDir}/scripts/manage_servers.py --action list
   
   

2. Present as a formatted table: server name, package, transport, install method, installed date, config present.

3. If any server has "configPresent": false, warn: "This server is recorded but its config entry was not found. It may need to be re-configured."

4. If the user asks about a specific server: text

   python3 {baseDir}/scripts/manage_servers.py --action status --server-id "<id>"
   
   

5. If no servers installed, suggest running a discovery search.

REMOVE — "Remove the X server"#

1. Confirm: "Remove [displayName]? This will remove the state record. You should also remove its entry from .mcp.json."

2. Run: text

   python3 {baseDir}/scripts/manage_servers.py --action remove --server-id "<id>"
   
   

3. Remind user to remove the corresponding entry from .mcp.json and restart OpenClaw.

UPDATE — "Update my MCP servers"#

1. Run version check: text

   python3 {baseDir}/scripts/version_check.py
   
   

   For a specific server: python3 {baseDir}/scripts/version_check.py --server-id "<id>"

2. Present results:

   • Servers with updateAvailable: true: show current vs latest version and the updateCommand.
   • Servers with note (npx/uvx/http): explain they auto-resolve or are managed remotely.
   • Docker servers: suggest docker pull to refresh the image.

3. If the user wants to update, run the updateCommand for each server via the Bash tool.

4. After updating, optionally run a health check to verify the updated server works.

HEALTH CHECK — "Is my X server working?" / "Test the GitHub MCP"#

1. Identify the server from the user's request.

2. Run: text

   python3 {baseDir}/scripts/health_check.py --server-id "<id>"
   
   

3. If status is "healthy":

   • Present the tool count and list a few tool names.
   • "Your [displayName] server is healthy with [toolCount] tools available."

4. If status is "unhealthy" or "error":

   • Show the error message.
   • Consult {baseDir}/references/troubleshooting.md for the specific error.
   • Update server status: python3 {baseDir}/scripts/manage_servers.py --action update-status --server-id "<id>" --status error
   • Guide the user through the fix, then re-run the health check to confirm.

TROUBLESHOOT — "X server isn't working" / "Why can't I use the GitHub tools?"#

1. Identify the server.

2. Run health check: text

   python3 {baseDir}/scripts/health_check.py --server-id "<id>"
   
   

3. Based on the error, consult {baseDir}/references/troubleshooting.md.

4. Guide the user through the fix step by step.

5. Re-run health check to confirm resolution.

6. If resolved, update status: python3 {baseDir}/scripts/manage_servers.py --action update-status --server-id "<id>" --status active

CONTRIBUTE — "Add my server to the marketplace" / "Contribute a server config"#

1. Gather server details from the user:

   • ID: lowercase, hyphenated (e.g., my-server)
   • Display Name: human-readable name
   • Description: what the server does
   • Package: npm/pip package name or Docker image
   • Transport: stdio or http
   • Install Method: npx, npm, uvx, pip, http, or docker
   • Categories: from the Categories list below
   • Required Env Vars: any tokens/keys needed
   • Tags: search keywords

2. Generate and validate the entry: text

   python3 {baseDir}/scripts/contribute_server.py --id "<id>" --display-name "<name>" --description "<desc>" --package "<pkg>" --transport "<transport>" --install-method "<method>" --categories "<cat1,cat2>" --tags "<tag1,tag2>" --required-env "<VAR1,VAR2>"
   
   

3. If valid is true: present the serverEntry JSON and the prBody template. Guide the user to submit a PR to the marketplace repository.

4. If valid is false: show the validationErrors and help the user fix them, then re-run.

Auth Guidance Pattern#

When a server requires environment variables:

1. List each required variable with its purpose (from authGuidance.instructions).

2. Provide the generation URL if available: "You can create one at [URL]".

3. Show the export command: export VAR_NAME=<your-value-here>

4. Remind about persistence: "Add this to ~/.zshrc (or ~/.bashrc) so it persists across sessions."

5. NEVER ask the user to paste their actual token in the chat. Guide them to set it in their shell.

6. NEVER store raw token values in config — only ${VAR_NAME} references.

7. Offer secrets manager (if available): Before telling the user to add export to .zshrc, check for a secrets manager: text

   python3 {baseDir}/scripts/secrets_helper.py --action detect
   
   

   If managers are found, offer the option: "I detected [manager name] on your system. Want to store this token there instead of in your shell profile? It's more secure." If yes, generate the store command: text

   python3 {baseDir}/scripts/secrets_helper.py --action store-command --manager "<manager>" --service "<server-name>" --env-var "<VAR_NAME>"
   
   

   Present the storeCommand for the user to run, then show the shellIntegration line to add to ~/.zshrc.

OAuth Servers#

When authGuidance.authType is "oauth":

1. Present the setup steps from authGuidance.oauthSetupSteps as a numbered list.
2. Mention the provider: "This server uses [provider] OAuth for authentication."
3. Link to reference doc: "For detailed OAuth setup instructions, see the OAuth patterns guide."
4. Guide through env vars: After OAuth setup, the user still needs to set the required env vars (e.g., GOOGLE_APPLICATION_CREDENTIALS).
5. Do NOT ask the user to paste credentials in the chat — guide them to set env vars in their shell.

Error Recovery#

• Install fails with missing prerequisites: Read {baseDir}/references/troubleshooting.md for the specific error and guide the user.
• Server not found in catalog: The search falls back to npm and Smithery registries automatically. If still not found, suggest checking https://github.com/modelcontextprotocol/servers for the official list or https://smithery.ai for community servers.
• Config generation fails: Show a manual config example from {baseDir}/references/transport-patterns.md and walk through it.
• Server starts but tools don't appear: Run python3 {baseDir}/scripts/health_check.py --server-id "<id>" to diagnose. Consult {baseDir}/references/troubleshooting.md.
• Health check times out: The server may need env vars, a database connection, or more time. Try increasing the timeout with --timeout 30.
• Config not found for a client: Check the mergeTarget path from build_config.py. See {baseDir}/references/troubleshooting.md for client-specific config paths.

Categories#

Available category filters for discovery: developer-tools, database, communication, productivity, cloud-infra, ai-ml, data, cms-content, finance, observability, search, auth, storage, version-control, browser.