# SERPHouse MCP Server **Connect AI assistants to live SERP data, Google verticals, and SEO intelligence — powered by [SERPHouse](https://serphouse.com).** 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.
[![TypeScript 5+](https://img.shields.io/badge/TypeScript-5%2B-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-Compatible-7B42BC)](https://modelcontextprotocol.io/) [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Install in VS Code](https://img.shields.io/badge/Install%20in-VS%20Code-blue?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=serphouse-mcp&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.serphouse.com%2Fmcp%22%2C%22headers%22%3A%7B%22SERPHOUSE_API%22%3A%22YOUR_SERPHouse_API_KEY%22%7D%7D) [![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-blue?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=serphouse-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNlcnBob3VzZS5jb20vbWNwIiwiaGVhZGVycyI6eyJTRVJQSE9VU0VfQVBJIjoiWU9VUl9TRVJQSG91c2VfQVBJX0tFWSJ9fQ==) [![Website](https://img.shields.io/badge/Website-serphouse.com-7B42BC)](https://serphouse.com) [![GitHub](https://img.shields.io/badge/GitHub-SERPHouse-181717?logo=github)](https://github.com/SERPHouse) [![LinkedIn](https://img.shields.io/badge/LinkedIn-SERPHouse-0A66C2?logo=linkedin)](https://linkedin.com/company/serphouse)

--- ## Table of Contents - [Why SERPHouse MCP](#why-serphouse-mcp) - [Quick Start (Hosted)](#quick-start-hosted) - [Authentication](#authentication) - [What You Can Ask](#what-you-can-ask) - [Tools Overview](#tools-overview) - [Self-Host Locally](#self-host-locally) - [Self-Host with Docker](#self-host-with-docker) - [Use with Local Llama Models (Ollama)](#use-with-local-llama-models-ollama) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [License](#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](https://www.serphouse.com). **2.** Add the server to your MCP client config using either [header-based](#option-a-header-recommended) or [URL-based](#option-b-url-path) authentication (see [Authentication](#authentication) for details). **Header (recommended):** ```json { "mcpServers": { "serphouse": { "url": "https://mcp.serphouse.com/mcp", "headers": { "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY" } } } } ``` **URL path:** ```json { "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: ` 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. ```json { "mcpServers": { "serphouse": { "url": "https://mcp.serphouse.com/mcp", "headers": { "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY" } } } } ``` Self-hosted example: ```json { "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. ```json { "mcpServers": { "serphouse": { "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp" } } } ``` Self-hosted example: ```json { "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. ```bash 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](#authentication) for both options): ```json { "mcpServers": { "serphouse": { "url": "http://localhost:3000/mcp", "headers": { "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY" } } } } ``` Or with URL-based auth: ```json { "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](#authentication). --- ## Self-Host with Docker Run the MCP server locally in Docker without installing Node.js. ```bash 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](#authentication): ```json { "mcpServers": { "serphouse": { "url": "http://localhost:3000/mcp", "headers": { "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY" } } } } ``` Or: ```json { "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`](https://github.com/jonigl/mcp-client-for-ollama) — 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](https://ollama.com) | | **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`: ```bash 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](#authentication): ```json { "mcpServers": { "serphouse-mcp": { "url": "https://mcp.serphouse.com/mcp", "headers": { "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY" } } } } ``` Or with URL-based auth: ```json { "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](https://www.serphouse.com). ### 3. Run the terminal client Launch the interactive interface, passing your config profile and target model: ```bash 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](https://ollama.com/search?c=tools) page. For models that can also process images returned by tools, see the Ollama [vision models](https://ollama.com/search?c=vision) 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](https://serphouse.com) | | 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. ```bash 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](LICENSE) — Copyright SERPHouse.