Search Evidence MCP

Original Python tools for evidence-first marketing work through ChatGPT-compatible MCP, OpenAI Responses agents, or a local CLI. Version 0.1.0 is an independently implemented alpha release; it is not a fork, a renamed Claude project, or a claim of feature parity with larger reference projects.

Working capabilities

• audit_html: static HTML metadata, robots, canonical, headings, image-alt, JSON-LD syntax, duplicate metadata and broken links within the supplied sample.

• analyze_search_console: weighted position, aggregate CTR, overlap candidates and an explicit review queue.

• crawl_site: opt-in same-origin public crawling with DNS/IP validation, pinned connections, redirect checks, robots rules and resource bounds.

Crawling is disabled until the operator sets ALLOWED_CRAWL_HOSTS=example.com (exact hosts, comma separated). Only standard HTTP(S) ports are accepted. It does not render JavaScript, measure Core Web Vitals, integrate directly with Google APIs, or certify schema eligibility. Search Console input is an export at date/query/page grain. No rank or AI-visibility score is fabricated.

Related MCP server: Wingate SEO MCP

Run the offline example

Python 3.11+ is required. No API key is needed for this example.

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
search-evidence-mcp tools
search-evidence-mcp run audit_html examples/demo.json --out output/demo
pytest -q
ruff check .

The command creates report.json, report.csv, report.md and an escaped report.html. JSON contains the complete structured result; CSV contains tabular findings or metrics when available. No output is published automatically. Inputs are validated and bounded. Errors fail explicitly instead of producing invented success.

Use with ChatGPT and OpenAI

search-evidence-mcp serve
# Local HTTP endpoint: http://127.0.0.1:8765/mcp
search-evidence-mcp serve --transport streamable-http
# Requires OPENAI_API_KEY and OPENAI_MODEL in your environment:
search-evidence-mcp agent examples/task.txt --out output/agent

See ChatGPT connection instructions. A ChatGPT connection needs a reachable endpoint or supported tunnel; this repository is not already hosted or connected to your account. The local HTTP service has no application authentication and must not be exposed directly. Deterministic MCP tools need no OpenAI key. The agent runner is optional and makes billable API calls.

Repository layout

Quality and scope

Tests cover important numerical, validation and trust boundaries, including a real MCP stdio discovery/call round trip. OpenAI agent tests use a fake client; they do not prove live model quality. CI runs tests, lint and dependency auditing across Python 3.11–3.13. See validation for the recorded local result and untested deployment boundaries.

This release prioritizes inspectable behavior over code volume. It does not claim to equal the references' line counts or broad feature sets. Scope and research explains the conceptual inspiration and remaining gaps. Source implementation was written independently; reference README descriptions informed the problem selection.

Read SECURITY.md before deployment. Contributions follow CONTRIBUTING.md and the community conduct policy. Licensed under MIT.