{"_id":"serphouse-mcp","_rev":"2-cc7fbc513b9467f77135f9b48270da1b","name":"serphouse-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"serphouse-mcp","version":"1.0.0","keywords":["serp api","scraping","serphouse mcp","serp scraping","serp data","serp intelligence","serp tasks","serp results","serp","mcp server","google serp api","yahoo serp api","sdk","serphouse","Search","Result","scrape"],"_id":"serphouse-mcp@1.0.0","maintainers":[{"name":"serphouse","email":"accounts@serphouse.com"}],"homepage":"https://github.com/serphouse/serphouse-mcp#readme","bugs":{"url":"https://github.com/serphouse/serphouse-mcp/issues"},"bin":{"serphouse-mcp":"dist/src/index.js"},"dist":{"shasum":"d149fdcab5ad8e5dab89ebb1ace51ac1ae82b3d5","tarball":"https://registry.npmjs.org/serphouse-mcp/-/serphouse-mcp-1.0.0.tgz","fileCount":3,"integrity":"sha512-dEF3/zL4pAfwciNWKxDaVG2cQOJpHKxpmvL6iK/MAR0WQKeOUT3FQt693VOdX5DhHtAAiQXBm9sCz7e2zfOS7w==","signatures":[{"sig":"MEYCIQDGN1QYufI5ax1r91EJvfznaElfRcQ/H550mqP5+x1cVgIhAPdS4IzlhtR4Mpq6PuWAmq8s2bhkOenk4ZbYeY10V/TM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13545},"type":"module","gitHead":"ce204b1831052269d83b98ab4d2faad2fb6ebe71","mcpName":"io.github.SERPHouse/serphouse-mcp","scripts":{"dev":"node --watch src/http.ts","build":"tsc","start":"node dist/src/http.js","dev:ins":"DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector npm run start:stdio","typecheck":"tsc --noEmit","start:stdio":"node dist/src/index.js"},"_npmUser":{"name":"serphouse","email":"accounts@serphouse.com"},"overrides":{"shell-quote":"1.8.4"},"publisher":"SERPHouse","repository":{"url":"git+https://github.com/serphouse/serphouse-mcp.git","type":"git"},"_npmVersion":"10.9.0","description":"SERPHouse MCP Server — connect AI assistants to live SERP data, Google verticals, and SEO intelligence.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^4.4.3","dotenv":"^17.4.2","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^25.9.0","@modelcontextprotocol/inspector":"^0.22.0"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/serphouse-mcp_1.0.0_1781617883840_0.20880710875794994","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"serphouse-mcp","version":"1.1.0","description":"SERPHouse MCP Server — connect AI assistants to live SERP data, Google verticals, and SEO intelligence.","mcpName":"io.github.SERPHouse/serphouse-mcp","type":"module","bin":{"serphouse-mcp":"dist/src/index.js"},"scripts":{"build":"tsc","start":"node dist/src/http.js","start:stdio":"node dist/src/index.js","dev":"node --watch src/http.ts","typecheck":"tsc --noEmit","dev:ins":"DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector npm run start:stdio","format":"npx prettier --write \"src/**/*.{js,jsx,ts,tsx,json,css,scss,md}\""},"devDependencies":{"@modelcontextprotocol/inspector":"^0.22.0","@types/node":"^25.9.0","typescript":"^5"},"peerDependencies":{"typescript":"^5"},"overrides":{"shell-quote":"1.8.4"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.4.3"},"repository":{"type":"git","url":"git+https://github.com/serphouse/serphouse-mcp.git"},"publisher":"SERPHouse","keywords":["serp api","scraping","serphouse mcp","serp scraping","serp data","serp intelligence","serp tasks","serp results","serp","mcp server","google serp api","yahoo serp api","sdk","serphouse","Search","Result","scrape"],"_id":"serphouse-mcp@1.1.0","gitHead":"64e508bb2d0c3e7feb4e4d714b84492ad688423d","bugs":{"url":"https://github.com/serphouse/serphouse-mcp/issues"},"homepage":"https://github.com/serphouse/serphouse-mcp#readme","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-aOOhVV0iPOLQS5ap1kcC3j9dnWT9G1JUbOuFpgc1eUdKyWR+1E9GPrqkxqAFCP9wwzUFNDqyuc67rfW71BwZfQ==","shasum":"f46c4286d48ab6c4e5a0d9e07fee3bf1408bf495","tarball":"https://registry.npmjs.org/serphouse-mcp/-/serphouse-mcp-1.1.0.tgz","fileCount":3,"unpackedSize":16452,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDztEzS7taa8gV2s219qHK/vTgqqMZELTVIsZdrbyNEwwIhAPKMpyXUOcsWmaEGPg6cw/ZlvVD2OwONL3hNZiYft2rF"}]},"_npmUser":{"name":"serphouse","email":"accounts@serphouse.com"},"directories":{},"maintainers":[{"name":"serphouse","email":"accounts@serphouse.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/serphouse-mcp_1.1.0_1783336120511_0.3852737096978758"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T13:51:23.309Z","modified":"2026-07-06T11:08:40.765Z","1.0.0":"2026-06-16T13:51:23.980Z","1.1.0":"2026-07-06T11:08:40.650Z"},"bugs":{"url":"https://github.com/serphouse/serphouse-mcp/issues"},"homepage":"https://github.com/serphouse/serphouse-mcp#readme","keywords":["serp api","scraping","serphouse mcp","serp scraping","serp data","serp intelligence","serp tasks","serp results","serp","mcp server","google serp api","yahoo serp api","sdk","serphouse","Search","Result","scrape"],"repository":{"type":"git","url":"git+https://github.com/serphouse/serphouse-mcp.git"},"description":"SERPHouse MCP Server — connect AI assistants to live SERP data, Google verticals, and SEO intelligence.","maintainers":[{"name":"serphouse","email":"accounts@serphouse.com"}],"readme":"<div align=\"center\">\n\n<img src=\"./assets/serphouse-logo.png\" alt=\"SERPHouse logo\" width=\"80\" />\n\n# SERPHouse MCP Server\n\n**Connect AI assistants to live SERP data, Google verticals, and SEO intelligence — powered by [SERPHouse](https://serphouse.com).**\n\nRun 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.\n\n<br />\n\n[![TypeScript 5+](https://img.shields.io/badge/TypeScript-5%2B-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-7B42BC)](https://modelcontextprotocol.io/)\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![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)\n[![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==)\n\n[![Website](https://img.shields.io/badge/Website-serphouse.com-7B42BC)](https://serphouse.com)\n[![GitHub](https://img.shields.io/badge/GitHub-SERPHouse-181717?logo=github)](https://github.com/SERPHouse)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-SERPHouse-0A66C2?logo=linkedin)](https://linkedin.com/company/serphouse)\n\n</div>\n\n---\n\n## Table of Contents\n\n- [Why SERPHouse MCP](#why-serphouse-mcp)\n- [Quick Start (Hosted)](#quick-start-hosted)\n- [Authentication](#authentication)\n- [What You Can Ask](#what-you-can-ask)\n- [Tools Overview](#tools-overview)\n- [Self-Host Locally](#self-host-locally)\n- [Self-Host with Docker](#self-host-with-docker)\n- [Use with Local Llama Models (Ollama)](#use-with-local-llama-models-ollama)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why SERPHouse MCP\n\n| | |\n|---|---|\n| **21 MCP tools** | Live Google, Bing, and Yahoo SERP, Google verticals, and account lookups — all exposed with typed schemas |\n| **Zero glue code** | Your assistant picks the right tool; you describe what you need in plain language |\n| **Hosted or self-hosted** | Use the managed endpoint at `https://mcp.serphouse.com/mcp`, or run the server on your own infrastructure |\n| **Built-in context** | MCP resources (`serphouse_capabilities`, `serphouse_constraints`, `serphouse_examples`) teach the AI usage rules automatically |\n\n---\n\n## Quick Start (Hosted)\n\nThe fastest path — no build step, no server to maintain.\n\n**1.** Get your API key from the [SERPHouse Dashboard](https://www.serphouse.com).\n\n**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).\n\n**Header (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"https://mcp.serphouse.com/mcp\",\n      \"headers\": {\n        \"SERPHOUSE_API\": \"YOUR_SERPHouse_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n**URL path:**\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp\"\n    }\n  }\n}\n```\n\n**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.\n\n> **One-click install:** Use the **Install in VS Code** or **Install in Cursor** badges above, then replace the placeholder API key with yours.\n\n---\n\n## Authentication\n\nThe server accepts your SERPHouse API key in two ways. Use whichever fits your MCP client.\n\n| Method | Endpoint | How to pass the key |\n|--------|----------|---------------------|\n| **Header** (recommended) | `POST /mcp` | `SERPHOUSE_API: <api_key>` request header |\n| **URL path** | `POST /{apiKey}/mcp` | Embed the key in the URL path |\n\nTools and resources can be discovered without a key. The API key is required only when calling SERPHouse API tools.\n\n### Option A: Header (recommended)\n\nBest when your MCP client supports custom headers. Keeps the key out of URLs and server access logs.\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"https://mcp.serphouse.com/mcp\",\n      \"headers\": {\n        \"SERPHOUSE_API\": \"YOUR_SERPHouse_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nSelf-hosted example:\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"http://localhost:3000/mcp\",\n      \"headers\": {\n        \"SERPHOUSE_API\": \"YOUR_SERPHouse_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Option B: URL path\n\nUseful when your client only supports a URL and cannot send custom headers.\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp\"\n    }\n  }\n}\n```\n\nSelf-hosted example:\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp\"\n    }\n  }\n}\n```\n\n> **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.\n\n---\n\n## What You Can Ask\n\nFor SEO teams, agencies, and SaaS marketers who need live search data inside their AI workflow — no dashboards, scripts, or context switching.\n\n| Why you use it | Example prompt |\n|----------------|----------------|\n| **Track your rankings** | *\"Where do we rank for 'crm software' on Google US desktop?\"* |\n| **Beat competitors** | *\"Who owns the top 5 spots for 'project management software' in London?\"* |\n| **Own local search** | *\"Top Google Local results for 'emergency plumber' in Chicago.\"* |\n| **Discover keywords** | *\"What does Autocomplete suggest for 'best saas for'?\"* |\n| **Monitor positions** | *\"Run a mobile Bing SERP check for our brand in NYC and report our rank.\"* |\n| **Multi-engine coverage** | *\"Compare Yahoo and Google news results for 'electric vehicles'.\"* |\n\n---\n\n## Tools Overview\n\nThe 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.\n\n### Reference\n\n| Tool | Description |\n|------|-------------|\n| `serphouse_domain_list` | Supported Google, Bing, and Yahoo search domains |\n| `serphouse_language_list` | Language codes by search engine type |\n| `serphouse_location_search` | Resolve city/country names to `loc_id` |\n| `serphouse_account_info` | Account balance and usage |\n\n### Google SERP\n\n| Tool | Description |\n|------|-------------|\n| `serphouse_google_web` | Google web search |\n| `serphouse_google_image` | Google image search |\n| `serphouse_google_news` | Google news search |\n| `serphouse_google_shop` | Google shopping search |\n| `serphouse_serp_google_advanced` | Advanced Google SERP with extended parameters (up to 100 results) |\n\n### Bing SERP\n\n| Tool | Description |\n|------|-------------|\n| `serphouse_bing_web` | Bing web search |\n| `serphouse_bing_image` | Bing image search |\n| `serphouse_bing_news` | Bing news search |\n\n### Yahoo SERP\n\n| Tool | Description |\n|------|-------------|\n| `serphouse_yahoo_web` | Yahoo web search |\n| `serphouse_yahoo_image` | Yahoo image search |\n| `serphouse_yahoo_news` | Yahoo news search |\n\n### Google Verticals\n\n| Tool | Description |\n|------|-------------|\n| `serphouse_google_jobs` | Google Jobs search |\n| `serphouse_google_autocomplete` | Google Autocomplete suggestions |\n| `serphouse_google_videos` | Google Videos results |\n| `serphouse_google_short_videos` | Google Short Videos (Shorts) |\n| `serphouse_google_forums` | Google Forums results |\n| `serphouse_google_local` | Google Local / Maps results |\n\n---\n\n## Self-Host Locally\n\nRun the server on your machine for full control or local development.\n\n```bash\ngit clone https://github.com/SERPHouse/serphouse-mcp.git\ncd serphouse-mcp\nnpm install\nnpm run build\nnpm start\n```\n\nThe server listens on `http://localhost:3000`. MCP endpoints:\n\n- `POST /mcp` — pass the API key via the `SERPHOUSE_API` header\n- `POST /{apiKey}/mcp` — pass the API key in the URL path\n\nPoint your MCP client at the local instance (see [Authentication](#authentication) for both options):\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"http://localhost:3000/mcp\",\n      \"headers\": {\n        \"SERPHOUSE_API\": \"YOUR_SERPHouse_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nOr with URL-based auth:\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp\"\n    }\n  }\n}\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compile TypeScript to `dist/` |\n| `npm start` | Run the HTTP server (`http://localhost:3000/mcp`) |\n| `npm run start:stdio` | Run the stdio transport server (local MCP process mode) |\n| `npm run dev` | Run the HTTP server with hot reload |\n| `npm run dev:ins` | Launch MCP Inspector against the stdio server for debugging |\n| `npm run typecheck` | Type-check without emitting files |\n\nHealth check: `GET http://localhost:3000/health`\n\n### Server Options\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3000` | HTTP listen port |\n| `HOST` | `0.0.0.0` | HTTP bind address |\n\nAuthentication supports both header and URL path. See [Authentication](#authentication).\n\n---\n\n## Self-Host with Docker\n\nRun the MCP server locally in Docker without installing Node.js.\n\n```bash\ndocker compose up -d\n```\n\nThe server runs at `http://localhost:3000/mcp` (header auth) or `http://localhost:3000/{apiKey}/mcp` (URL auth).\n\nConnect your MCP client using either method from [Authentication](#authentication):\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"http://localhost:3000/mcp\",\n      \"headers\": {\n        \"SERPHOUSE_API\": \"YOUR_SERPHouse_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nOr:\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse\": {\n      \"url\": \"http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## Use with Local Llama Models (Ollama)\n\nHook 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.\n\n### Prerequisites\n\n| Requirement | Notes |\n|-------------|-------|\n| **Tool-calling Llama model** | A model that supports tool calls (e.g. `llama3.1`, `llama3.2`) installed and running via [Ollama](https://ollama.com) |\n| **Python 3.10+** | Required to run the `ollmcp` terminal client |\n| **Node.js** | Required to run the SERPHouse MCP server via `npx` |\n\n### 1. Install `ollmcp`\n\n`ollmcp` is a Python client, so install it globally with `pip`:\n\n```bash\npip install --upgrade ollmcp\n```\n\n### 2. Create a `config.json` file\n\nThe 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):\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse-mcp\": {\n      \"url\": \"https://mcp.serphouse.com/mcp\",\n      \"headers\": {\n        \"SERPHOUSE_API\": \"YOUR_SERPHouse_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nOr with URL-based auth:\n\n```json\n{\n  \"mcpServers\": {\n    \"serphouse-mcp\": {\n      \"url\": \"https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp\"\n    }\n  }\n}\n```\n\n> Replace `YOUR_SERPHouse_API_KEY` with your active key from the [SERPHouse Dashboard](https://www.serphouse.com).\n\n### 3. Run the terminal client\n\nLaunch the interactive interface, passing your config profile and target model:\n\n```bash\nollmcp --servers-json config.json --model llama3.1\n```\n\n###### Once the terminal UI loads:\n\n1. Select your target Llama model from the model list.\n2. Submit a prompt that needs live web data — e.g. *\"Look up the top Google results for 'best developer tools' using SERPHouse.\"*\n3. Watch your local Llama model call the SERPHouse tools and turn real-time SERP data into a conversational answer.\n\n### Compatible Models\n\nThe following Ollama models work well with tool use:\n\n- gemma4\n- qwen3.5\n- lfm2.5-thinking\n- llama3.2\n- mistral\n\nFor a complete list of Ollama models with tool use capabilities, visit the official [Ollama models](https://ollama.com/search?c=tools) page.\n\nFor models that can also process images returned by tools, see the Ollama [vision models](https://ollama.com/search?c=vision) page.\n\n---\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| Missing API key | Send `SERPHOUSE_API` header on `POST /mcp`, or use `POST /{apiKey}/mcp` with the key in the URL path |\n| Invalid key | Verify your key in the [SERPHouse dashboard](https://serphouse.com) |\n| Credit exhausted | Check balance with `serphouse_account_info` |\n| 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. |\n| Connection refused | Confirm the server is running and the URL/port is correct |\n\n---\n\n## Contributing\n\nContributions are welcome. Please keep changes focused and match existing code style.\n\n```bash\ngit checkout -b feature/your-feature\nnpm install\n# make changes\nnpm run typecheck\ngit commit -m \"Add your feature\"\ngit push origin feature/your-feature\n```\n\nThen open a Pull Request. Update this README if you change setup or configuration.\n\n---\n\n## License\n\n[MIT License](LICENSE) — Copyright SERPHouse.\n","readmeFilename":"README.md"}