MCP recipes

These are working patterns for a connected agent. Paste the request, adapt the details in brackets, and the agent walks the numbered flow. Anything shown in code is a GeckoGrid MCP tool the agent calls on your machine. For long waits, get_scan and report_get accept wait_seconds (up to 120) so the agent waits on a result instead of polling you for updates.

Weekly client report

What you say:

Build this week’s client report for [project]. Pull the period summary and keyword history, export before and after maps for the keywords that moved most, and assemble it in my branding as a PDF.

What the agent does:

1. Finds the project with get_projects(kind: "client").
2. Pulls the period in one call with get_project_period_summary, passing the week’s from and to dates (the default period is the last 30 days). Each keyword comes back with its baseline scan, latest scan, the change, and competitor movement.
3. Pulls get_keyword_history for trend lines, using the included metric definitions so the two average ranks are never mixed up.
4. Exports the baseline and latest heatmaps with export_scan_image, one image at a time, and looks at each one before describing it.
5. Optionally adds profile and website health with client_audit_create, waiting via report_get(id, wait_seconds: 120).
6. Assembles the report in the branding you agreed once, and writes the PDF itself. GeckoGrid supplies the data; your agent builds the client report.

Prospect pipeline

What you say:

Create a prospect report for [business], [address or Google Maps link], keyword [keyword]. Scan it once, build the scored report with email and DM outreach, and export the leave-behind.

What the agent does:

1. Resolves the location with geocode_address, which also accepts a Google Maps link and returns the place name.
2. Creates the project with create_project using kind: "prospect", so it lands on the Prospects tab, away from your clients.
3. Checks the daily advisory count with get_daily_scan_info, starts the scan with start_scan, and waits with get_scan(scan_id, wait_seconds: 120).
4. Matches the business in the scan results with get_scan_results to get its place_id, asking you if the name does not match exactly.
5. Creates the report with report_create(scan_id, place_id) and waits for collection with report_get(id, wait_seconds: 120). Collection runs on a serial queue and takes a minute or two.
6. Reads the report, looks at the screenshots and grid images from report_get_assets, then writes the headline, summary, design critique, fix plan, and outreach copy with report_set_section. Optional extras: report_run_market for search volume (it bills your DataForSEO account, once per report) and report_set_extras for money figures you supplied.
7. Exports the leave-behind with report_render(mode: "leave_behind"). The leave-behind always renders in the dark theme; theme: "light" is only accepted with mode: "full", so use the full render when the prospect will print it.

Instant rank check

What you say:

Scan [keyword] for [project] once and export the heatmap at close zoom to my Downloads folder.

What the agent does:

1. Checks today’s advisory scan count with get_daily_scan_info.
2. Starts the scan with start_scan and waits on it with get_scan(scan_id, wait_seconds: 120), repeating if the scan outlasts the wait.
3. Exports the heatmap with export_scan_image(scan_id, zoom: "close"). With no output path the PNG lands in Downloads, named after the business and keyword.

If there is no project yet, the agent first geocodes the address with geocode_address and creates the project with create_project.

Watch a competitor

What you say:

Who is beating [project] on [keyword]? Show me the leaderboard, the trend over recent scans, and export that competitor’s grid.

What the agent does:

1. Finds the latest completed scan for the keyword with get_project_scans, newest first, or starts a fresh one with start_scan.
2. Pulls the leaderboard with get_scan_competitors: every business on the grid with presence, average, best and worst rank, ratings, reviews, and a top-3 benchmark against your business.
3. Pulls get_competitor_trends(project_id, keyword) for the same competitors across up to 20 recent scans, oldest to newest, to show who is gaining ground.
4. Exports the competitor’s own heatmap with export_scan_image(scan_id, place_id), which renders that business’s grid from the same scan.
5. On an ongoing basis, scheduled or on-demand rescans extend the trend. If you pitched that competitor as a prospect, report_compare lines up two of its reports, before and after, with the movement called out.

The prospect pipeline skill (prospect-pipeline) covers the full pitch flow, and the client report skill (client-report) covers reporting to a paying client. See MCP analyst skills for when the agent loads each one.