ValueSERP MCP

Give Claude and Cursor real-time Google SERP data.

A local Model Context Protocol server that wraps the ValueSERP API. Ask your AI assistant to check rankings, research competitors, resolve search locations, monitor credits, or schedule bulk keyword tracking, all without leaving the chat.

Works with Cursor, Claude Desktop, and any MCP-compatible client.

---

Why this exists

SEO research in an AI chat usually means copy-pasting SERPs or hoping the model remembers stale results. ValueSERP returns live, structured Google data (organic results, local pack, knowledge graph, AI overviews, and more). This MCP exposes that API as tools your assistant can call directly.

You: "Who ranks for 'best running shoes' in New York?"
AI:  → google_search(q="best running shoes", location="New York,New York,United States")
     → Returns live positions, domains, and snippets

No browser automation. No scraping maintenance. Just API calls.

---

Features

• Real-time Google search with location, device, language, and country targeting
• Location lookup to resolve city/country names before searching
• Account monitoring for credits, rate limits, and usage history
• Batch management for bulk and scheduled keyword tracking (up to 15,000 searches per batch)
• Summarized responses by default to keep context windows manageable
• Zero infrastructure runs locally over stdio, same pattern as other local MCP servers

---

Tools

Tool	Description	Credits
google_search	Live Google SERP lookup	1 per successful search
list_locations	Resolve locations for localized searches	Free
get_account	Plan, credits remaining, usage history	Free
list_batches	List batches on your account	Free
get_batch	Get batch metadata	Free
create_batch	Create a new batch	Free
add_batch_searches	Add up to 1,000 searches to a batch	Free
start_batch	Run a batch on demand	1 per search in batch
list_batch_result_sets	List downloadable result sets	Free
get_batch_result_set	Get download links for a result set	Free

google_search returns a summarized JSON payload by default (organic results, local pack, knowledge graph, related searches, etc.). Pass include_raw=true for the full API response.

---

Quick start

1. Get a ValueSERP API key

Sign up at app.valueserp.com. The free trial includes 100 searches, no credit card required.

Copy your API key from the account page.

2. Clone and install

git clone https://github.com/jefflouella/valueserp-mcp.git
cd valueserp-mcp

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Smoke test (optional)

export VALUESERP_API_KEY="demo"
python3 -c "
from valueserp_mcp_server import google_search, get_account
print('Credits:', get_account()['account_info']['monthly_credits_remaining'])
print(google_search('pizza', num=3)['organic_results'])
"

4. Connect to your AI client

See Cursor setup or Claude Desktop setup below.

---

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "valueserp-local": {
      "command": "/ABSOLUTE/PATH/TO/valueserp-mcp/.venv/bin/python3",
      "args": [
        "/ABSOLUTE/PATH/TO/valueserp-mcp/valueserp_mcp_server.py"
      ],
      "env": {
        "VALUESERP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Cursor or reload MCP servers.

---

Claude Desktop

Add to your Claude config:

OS	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Use the same mcpServers block as the Cursor setup. Fully quit and reopen Claude Desktop (not just close the window).

Note: This is for Claude Desktop only. Claude on the web does not support local MCP servers.

---

Example prompts

Once connected, try asking:

• "How many ValueSERP credits do I have left?"
• "Search Google for 'organic coffee beans' in the United States and summarize the top 5 results."
• "Find the ValueSERP location for London, UK, then search for 'co-working spaces' there."
• "What domains rank for 'best CRM software' on mobile in the US?"
• "Create a manual batch called 'weekly rank check' and add searches for these 10 keywords."

---

google_search parameters

Common parameters exposed as tool arguments:

Parameter	Example	Purpose
q	"best pizza nyc"	Search query (required)
location	"New York,New York,United States"	Geo-targeted results
google_domain	"google.co.uk"	Google TLD
gl	"us"	Country code
hl	"en"	UI language
device	"mobile"	desktop, mobile, or tablet
search_type	"images"	web, images, news, videos, shopping
page	2	Pagination
num	10	Results per page
include_ai_overview	true	Include Google AI Overview
include_raw	true	Return full API response
extra_params	{"max_page": 3}	Pass-through for any Search API param

Use list_locations to resolve human-readable place names to full_name values for the location parameter.

---

Architecture

flowchart LR
  AI[Cursor / Claude Desktop] -->|stdio MCP| MCP[valueserp_mcp_server.py]
  MCP --> Search["GET /search"]
  MCP --> Locations["GET /locations"]
  MCP --> Account["GET /account"]
  MCP --> Batches["/batches/*"]
  Search & Locations & Account & Batches --> API[api.valueserp.com]

Loading

The server is a thin Python wrapper around the ValueSERP REST API using FastMCP and httpx. Authentication is via the VALUESERP_API_KEY environment variable (also accepts VALUE_SERP_API_KEY).

---

Environment variables

Variable	Required	Description
VALUESERP_API_KEY	Yes	Your ValueSERP API key
VALUE_SERP_API_KEY	Alt	Accepted alias for the above

Copy .env.example to .env for local development. Never commit your API key.

---

Cost and limits

• Only successful searches consume credits.
• Account, location, and batch management calls are free.
• Real-time searches can take up to 180 seconds; the server uses that timeout.
• Batch result sets are retained for 14 days.
• See ValueSERP pricing for plan details.

---

Requirements

• Python 3.10+
• A ValueSERP API key
• An MCP-compatible client (Cursor, Claude Desktop, etc.)

Dependencies: mcp, httpx

---

Related links

• ValueSERP API docs
• ValueSERP API playground
• Model Context Protocol

---

License

MIT