How to Build a Lead List (in Gemini CLI)

TL;DR

• Gemini CLI reaches LeadOcean through one gemini mcp add command and a browser sign-in. You size the audience for free, then export it as a CSV.
• It takes about 15 minutes. The example audience (US engineering directors at software companies with 201 to 500 staff) spends about 105 records. The export step needs Solo or above.
• Counts, filter lookups and enum lookups cost nothing. Only rows you receive count.

Prerequisites

• A LeadOcean account from app.leadocean.io. The free plan has no card and 1,000 records, one-off.
• Gemini CLI installed, with a local browser on the same machine. The Gemini CLI MCP docs, October 2026, say OAuth needs a browser and a localhost redirect. It will not work over plain SSH.
• One thing to check first. The same docs carry a notice that Gemini CLI was replaced by Antigravity CLI on June 18th, 2026 for unpaid tier and Google One users. If that is you, this recipe may not apply to your install.
• For the REST fallback in Step 5: a key in your shell as $LEADOCEAN_API_KEY, plus curl and jq.

export LEADOCEAN_API_KEY="paste-your-key-here"

The MCP steps need no key. Setup details for every client, Gemini CLI included, are on MCP for agents.

Step 1: Add the LeadOcean MCP server

Gemini CLI has an mcp add command for remote servers. The docs list --transport http for the streamable HTTP transport, and the default scope is project. Use --scope user to load it in every folder.

gemini mcp add --transport http --scope user leadocean https://api.leadocean.io/mcp
gemini mcp list

gemini mcp list shows each server with its connection status. A fresh server may show as disconnected until you sign in.

The command writes to settings.json. You can write the entry by hand instead. The docs name the field httpUrl for HTTP streaming.

{
  "mcpServers": {
    "leadocean": {
      "httpUrl": "https://api.leadocean.io/mcp"
    }
  }
}

Do not add a headers block. LeadOcean signs you in with OAuth 2.1, so there is nothing to paste. Keep the server name free of underscores: the docs warn that Gemini CLI splits tool names on the first underscore after mcp_.

Step 2: Sign in and check the tools

Start gemini and run the auth command from the docs. Your browser opens on LeadOcean. Sign in, approve, and return to the terminal.

/mcp auth leadocean
/mcp

The OAuth server supports dynamic client registration at https://api.leadocean.io/oauth/register (scope mcp), so the CLI registers itself. Gemini CLI stores the tokens in ~/.gemini/mcp-oauth-tokens.json.

The /mcp command lists the server's tools. There are 13 LeadOcean tools, and seven never spend records: lead count, company count, filter list, enum list, account, get export and list exports. Gemini CLI prefixes every MCP tool with mcp_ and the server name.

Ask for your balance before anything else.

Use leadocean_get_account. Tell me my plan and how many records I have left.
Do not search anything.

To fence off spending, add "excludeTools": ["leadocean_export_leads"] to the server entry until Step 5. The docs say excluded tools are hidden from the model.

Step 3: Size the audience for free

Write the audience as filters. This example is engineering directors at US software companies with 201 to 500 staff. Filters take exact values, so resolve the industry string first.

Use leadocean_list_enum_values for industry with q "software". Then use
leadocean_count_leads with jobLevel ["Director"], jobFunction ["Engineering"],
industry ["Software Development"], employeeRange ["201-500"], country ["US"],
facets false. Report the total and say which email statuses it counted.
Do not call any tool that spends records.

Gemini CLI asks you to confirm each MCP tool call unless the server is marked trust. Do not set trust for this server. Reading the arguments before you approve is your spending control.

The REST version is a people search with count=true as a query parameter and limit at 1. It returns meta.total and no rows.

curl -s "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "jobLevel": ["Director"],
    "jobFunction": ["Engineering"],
    "industry": ["Software Development"],
    "employeeRange": ["201-500"],
    "country": ["US"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 1
  }' | jq '.meta'

If the number is too big or too small, change one filter and count again. Counting is free however often you do it.

Step 4: Spot-check five rows

Look at real rows before you pull 100 of them. Search returns thin records and no addresses.

Use leadocean_search_leads with the same filters and limit 5. Show a table of name,
job title, company, company domain and email_status. Flag any title that is not an
engineering leader so I can add it to excludeTitle.

Each person returned costs one record, so this step spends 5. The REST version is the same body with limit set to 5 and no count. Add excludeTitle (for example ["assistant","intern"]) if the sample shows noise. Search pages take limit 1 to 100 and continue with cursor.

Step 5: Export the list to CSV

Use an export for the bulk pull. Chat is a poor place for 100 rows, and an export writes one file. An export takes up to 50,000 rows a request and 500,000 a day. Bulk CSV export is not on Free: it is included on Solo at $97 a month and on Agency at $497 a month.

Start a leadocean export with the filters above, limit 100, preset full. Poll it
with leadocean_get_export until it is done, then give me the download link.

The REST route does the same job. Read perRow in the reply first: the API reference says it is 1, or 2 when a column needs the full record. Poll every pollAfter seconds, then download when the status is done.

curl -s https://api.leadocean.io/v1/exports \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "name": "US engineering directors at software companies",
    "filters": {
      "jobLevel": ["Director"],
      "jobFunction": ["Engineering"],
      "industry": ["Software Development"],
      "employeeRange": ["201-500"],
      "country": ["US"],
      "emailStatus": ["verified", "catch_all_valid", "catch_all"]
    },
    "limit": 100,
    "preset": "full"
  }' | tee export.json | jq '.data | {id, status, requested, perRow, remaining, pollAfter}'

ID=$(jq -r '.data.id' export.json)
curl -s https://api.leadocean.io/v1/exports/$ID/download -H "x-api-key: $LEADOCEAN_API_KEY" -o leads.csv

Before you load the CSV anywhere, read the email_status column. Verified and catch_all_valid addresses are the safest to send to. Bounced emails are not refunded, so drop anything you do not trust.

The LeadOcean app has the same export on its Exports page. It has a filter builder, a column picker, the record price before you start and a Download button.

What you get

The Step 3 run is real. On 21 October 2026 we ran leadocean_list_enum_values and leadocean_count_leads with the filters above. Both are free. The enum lookup for "software" returned seven values, among them Software Development:

{
  "name": "industry",
  "total": 534,
  "matched": 7,
  "values": [
    "Computer Software",
    "Data Security Software Products",
    "Desktop Computing Software Products",
    "Embedded Software Products",
    "IT System Custom Software Development",
    "Mobile Computing Software Products",
    "Software Development"
  ]
}

The count returned this.

{
  "total": 772,
  "totalIsExact": true,
  "totalAll": 1585,
  "distinctCompanies": 408,
  "credits": 0,
  "defaults": "Counted only addresses worth sending to (emailStatus: verified or catch_all_valid or catch_all), which is this tool's default.",
  "sample": 1,
  "hasMore": true
}

The total describes the mailable audience, meaning verified, catch_all_valid or catch_all emails, at 408 companies. Everyone matching the other filters is totalAll, 1,585 people. Your number will differ as the data refreshes.

We did not run the spot-check or the export for this page, because both spend records. The export request returns HTTP 202 and a job. This is the response shape from the API reference, with placeholder values.

{
  "success": true,
  "data": {
    "id": "<export id>",
    "name": "US engineering directors at software companies",
    "status": "queued",
    "requested": 100,
    "perRow": "<records per row>",
    "remaining": "<records left after this reservation>",
    "pollAfter": "<seconds>",
    "file": null
  }
}

The finished download is a plain .csv, one row per person. Records are reserved when the export is admitted, and rows never written are released. The run costs about 105 records if perRow is 1: 5 for the spot-check and 100 for the export. At 2 a row it is about 205. That is an estimate from the row counts, not a measured run.

Troubleshooting

FAQ