# Serphouse Mcp

> MCP server for SERPHouse API. Enables LLMs to perform live, geo-targeted Search engine queries. Built with TypeScript.

- **Type:** MCP server
- **Install:** `agentstack add mcp-serphouse-serphouse-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SERPHouse](https://agentstack.voostack.com/s/serphouse)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SERPHouse](https://github.com/SERPHouse)
- **Source:** https://github.com/SERPHouse/serphouse-mcp
- **Website:** https://mcp.serphouse.com/mcp

## Install

```sh
agentstack add mcp-serphouse-serphouse-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](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)
[](cursor://anysphere.cursor-deeplink/mcp/install?name=serphouse-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNlcnBob3VzZS5jb20vbWNwIiwiaGVhZGVycyI6eyJTRVJQSE9VU0VfQVBJIjoiWU9VUl9TRVJQSG91c2VfQVBJX0tFWSJ9fQ==)

[](https://serphouse.com)
[](https://github.com/SERPHouse)
[](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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SERPHouse](https://github.com/SERPHouse)
- **Source:** [SERPHouse/serphouse-mcp](https://github.com/SERPHouse/serphouse-mcp)
- **License:** MIT
- **Homepage:** https://mcp.serphouse.com/mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-serphouse-serphouse-mcp
- Seller: https://agentstack.voostack.com/s/serphouse
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.