SERPHouse MCP Server

Connect AI assistants to live SERP data, Google verticals, and SEO intelligence — powered by SERPHouse.

Run Google, Bing, and Yahoo searches, resolve locations, and query Jobs, Local, Videos, and more — directly from Cursor, VS Code, Claude Desktop, or any MCP-compatible client. No custom API integration required.

Table of Contents

• Why SERPHouse MCP
• Quick Start (Hosted)
• Authentication
• What You Can Ask
• Tools Overview
• Self-Host Locally
• Self-Host with Docker
• Use with Local Llama Models (Ollama)
• Troubleshooting
• Contributing
• License

Why SERPHouse MCP

| | | |---|---| | 21 MCP tools | Live Google, Bing, and Yahoo SERP, Google verticals, and account lookups — all exposed with typed schemas | | Zero glue code | Your assistant picks the right tool; you describe what you need in plain language | | Hosted or self-hosted | Use the managed endpoint at https://mcp.serphouse.com/mcp, or run the server on your own infrastructure | | Built-in context | MCP resources (serphouse_capabilities, serphouse_constraints, serphouse_examples) teach the AI usage rules automatically |

Quick Start (Hosted)

The fastest path — no build step, no server to maintain.

1. Get your API key from the SERPHouse Dashboard.

2. Add the server to your MCP client config using either header-based or URL-based authentication (see Authentication for details).

Header (recommended):

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

URL path:

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

3. Start chatting. Ask your assistant to search Google, Bing, or Yahoo, look up locations, fetch jobs, or check your account — it will route to the correct tool.

One-click install: Use the Install in VS Code or Install in Cursor badges above, then replace the placeholder API key with yours.

Authentication

The server accepts your SERPHouse API key in two ways. Use whichever fits your MCP client.

| Method | Endpoint | How to pass the key | |--------|----------|---------------------| | Header (recommended) | POST /mcp | SERPHOUSE_API: <api_key> request header | | URL path | POST /{apiKey}/mcp | Embed the key in the URL path |

Tools and resources can be discovered without a key. The API key is required only when calling SERPHouse API tools.

Option A: Header (recommended)

Best when your MCP client supports custom headers. Keeps the key out of URLs and server access logs.

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Self-hosted example:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Option B: URL path

Useful when your client only supports a URL and cannot send custom headers.

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Self-hosted example:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Note: URL-based auth places the API key in the request path, which may appear in proxy logs or browser history. Prefer the header method when possible.

What You Can Ask

For SEO teams, agencies, and SaaS marketers who need live search data inside their AI workflow — no dashboards, scripts, or context switching.

| Why you use it | Example prompt | |----------------|----------------| | Track your rankings | "Where do we rank for 'crm software' on Google US desktop?" | | Beat competitors | "Who owns the top 5 spots for 'project management software' in London?" | | Own local search | "Top Google Local results for 'emergency plumber' in Chicago." | | Discover keywords | "What does Autocomplete suggest for 'best saas for'?" | | Monitor positions | "Run a mobile Bing SERP check for our brand in NYC and report our rank." | | Multi-engine coverage | "Compare Yahoo and Google news results for 'electric vehicles'." |

Tools Overview

The server exposes 21 tools across five categories. Google and Bing SERP requests require exactly one location field — loc (e.g. Austin,Texas,United States) or loc_id (from serphouse_location_search). Never send both or omit both on those endpoints. Yahoo SERP tools do not require location.

Reference

| Tool | Description | |------|-------------| | serphouse_domain_list | Supported Google, Bing, and Yahoo search domains | | serphouse_language_list | Language codes by search engine type | | serphouse_location_search | Resolve city/country names to loc_id | | serphouse_account_info | Account balance and usage |

Google SERP

| Tool | Description | |------|-------------| | serphouse_google_web | Google web search | | serphouse_google_image | Google image search | | serphouse_google_news | Google news search | | serphouse_google_shop | Google shopping search | | serphouse_serp_google_advanced | Advanced Google SERP with extended parameters (up to 100 results) |

Bing SERP

| Tool | Description | |------|-------------| | serphouse_bing_web | Bing web search | | serphouse_bing_image | Bing image search | | serphouse_bing_news | Bing news search |

Yahoo SERP

| Tool | Description | |------|-------------| | serphouse_yahoo_web | Yahoo web search | | serphouse_yahoo_image | Yahoo image search | | serphouse_yahoo_news | Yahoo news search |

Google Verticals

| Tool | Description | |------|-------------| | serphouse_google_jobs | Google Jobs search | | serphouse_google_autocomplete | Google Autocomplete suggestions | | serphouse_google_videos | Google Videos results | | serphouse_google_short_videos | Google Short Videos (Shorts) | | serphouse_google_forums | Google Forums results | | serphouse_google_local | Google Local / Maps results |

Self-Host Locally

Run the server on your machine for full control or local development.

git clone https://github.com/SERPHouse/serphouse-mcp.git
cd serphouse-mcp
npm install
npm run build
npm start

The server listens on http://localhost:3000. MCP endpoints:

• POST /mcp — pass the API key via the SERPHOUSE_API header
• POST /{apiKey}/mcp — pass the API key in the URL path

Point your MCP client at the local instance (see Authentication for both options):

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Or with URL-based auth:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Commands

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to dist/ | | npm start | Run the HTTP server (http://localhost:3000/mcp) | | npm run start:stdio | Run the stdio transport server (local MCP process mode) | | npm run dev | Run the HTTP server with hot reload | | npm run dev:ins | Launch MCP Inspector against the stdio server for debugging | | npm run typecheck | Type-check without emitting files |

Health check: GET http://localhost:3000/health

Server Options

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | HTTP listen port | | HOST | 0.0.0.0 | HTTP bind address |

Authentication supports both header and URL path. See Authentication.

Self-Host with Docker

Run the MCP server locally in Docker without installing Node.js.

docker compose up -d

The server runs at http://localhost:3000/mcp (header auth) or http://localhost:3000/{apiKey}/mcp (URL auth).

Connect your MCP client using either method from Authentication:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Or:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Use with Local Llama Models (Ollama)

Hook up your SERPHouse MCP Server to a local Llama model (e.g. Llama 3.1 or 3.2) using ollmcp — an interactive terminal UI client that brings real-time search engine power straight to your local LLM workflow.

Prerequisites

| Requirement | Notes | |-------------|-------| | Tool-calling Llama model | A model that supports tool calls (e.g. llama3.1, llama3.2) installed and running via Ollama | | Python 3.10+ | Required to run the ollmcp terminal client | | Node.js | Required to run the SERPHouse MCP server via npx |

1. Install ollmcp

ollmcp is a Python client, so install it globally with pip:

pip install --upgrade ollmcp

2. Create a config.json file

The client needs a configuration profile that tells it how to connect to the SERPHouse server and pass your API credentials. Create a config.json in your working folder using either auth method from Authentication:

{
  "mcpServers": {
    "serphouse-mcp": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Or with URL-based auth:

{
  "mcpServers": {
    "serphouse-mcp": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Replace YOUR_SERPHouse_API_KEY with your active key from the SERPHouse Dashboard.

3. Run the terminal client

Launch the interactive interface, passing your config profile and target model:

ollmcp --servers-json config.json --model llama3.1

Once the terminal UI loads:

1. Select your target Llama model from the model list.
2. Submit a prompt that needs live web data — e.g. "Look up the top Google results for 'best developer tools' using SERPHouse."
3. Watch your local Llama model call the SERPHouse tools and turn real-time SERP data into a conversational answer.

Compatible Models

The following Ollama models work well with tool use:

• gemma4
• qwen3.5
• lfm2.5-thinking
• llama3.2
• mistral

For a complete list of Ollama models with tool use capabilities, visit the official Ollama models page.

For models that can also process images returned by tools, see the Ollama vision models page.

Troubleshooting

| Issue | Fix | |-------|-----| | Missing API key | Send SERPHOUSE_API header on POST /mcp, or use POST /{apiKey}/mcp with the key in the URL path | | Invalid key | Verify your key in the SERPHouse dashboard | | Credit exhausted | Check balance with serphouse_account_info | | Location error | For Google and Bing tools, include loc or loc_id (not both); use serphouse_location_search to resolve IDs. Yahoo SERP tools do not require location. | | Connection refused | Confirm the server is running and the URL/port is correct |

Contributing

Contributions are welcome. Please keep changes focused and match existing code style.

git checkout -b feature/your-feature
npm install
# make changes
npm run typecheck
git commit -m "Add your feature"
git push origin feature/your-feature

Then open a Pull Request. Update this README if you change setup or configuration.

License

MIT License — Copyright SERPHouse.