Skip to main content

MCP Server

Pipl provides an MCP Server that connects the Pipl Search API to AI assistants like Cursor, Claude Desktop, Windsurf, and any other MCP-compatible client. Once configured, you can run identity searches using natural language — instead of writing API calls or switching to Postman, you can ask your assistant things like "Search for john.smith@example.com" and get full identity results inline.

You can connect in two ways:

  • Remote MCP (recommended) — hosted by Pipl at https://mcp.pipl.com/search/. No install, no local Node.js, always up to date.
  • Local MCP — run the open-source server from GitHub on your own machine. Useful for offline development, air-gapped environments, or when you want to extend the server.

Both options expose the same Search tools and require only a valid Pipl API key.

What You Can Do​

The MCP server exposes the full power of the Pipl Search API through a set of purpose-built tools:

ToolDescription
search_by_emailSearch by email address
search_by_phoneSearch by phone number (international format, e.g. +15551234567)
search_by_nameSearch by name, optionally combined with email, phone, or address
search_by_addressSearch by physical address
search_by_usernameSearch by social username (e.g. superman@facebook)
search_by_urlSearch by social profile URL (e.g. LinkedIn, Facebook)
search_by_search_pointerFollow up on a previous result using a search pointer
search_by_personAdvanced search with a structured person JSON object
search_rawRaw API call with any combination of parameters

Each tool returns identity data including names, emails, phone numbers, addresses, jobs, education, social profiles, and more.

Prerequisites​

The remote MCP is hosted by Pipl at https://mcp.pipl.com/search/ and serves the Pipl Search product. Authentication is handled per-request by passing your API key as a Bearer token in the Authorization header.

Cursor IDE​

Open Cursor Settings > MCP, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "pipl": {
      "url": "https://mcp.pipl.com/search/",
      "headers": {
        "Authorization": "Bearer YOUR_PIPL_API_KEY"
      }
    }
  }
}

Claude Desktop​

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pipl": {
      "url": "https://mcp.pipl.com/search/",
      "headers": {
        "Authorization": "Bearer YOUR_PIPL_API_KEY"
      }
    }
  }
}

Replace YOUR_PIPL_API_KEY with your Pipl API key. Restart your MCP client for the changes to take effect.

Why use the remote MCP

You don't need to clone a repo, install Node.js, or rebuild after updates — new tools and fixes are deployed automatically.

Option 2: Local MCP (Self-Hosted)​

Prefer to run the MCP server on your own machine? Clone the open-source server from GitHub:

git clone https://github.com/piplcom/piplapis-search-mcp.git
cd piplapis-search-mcp
npm install

Cursor IDE​

Open Cursor Settings > MCP, or edit ~/.cursor/mcp.json directly:

macOS / Linux:

{
  "mcpServers": {
    "piplapis-search": {
      "command": "node",
      "args": ["/absolute/path/to/piplapis-search-mcp/index.js"],
      "env": {
        "PIPL_API_KEY": "YOUR_PIPL_API_KEY"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "piplapis-search": {
      "command": "node",
      "args": ["C:\\Users\\username\\piplapis-search-mcp\\index.js"],
      "env": {
        "PIPL_API_KEY": "YOUR_PIPL_API_KEY"
      }
    }
  }
}

Restart Cursor for changes to take effect.

Claude Desktop​

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "piplapis-search": {
      "command": "node",
      "args": ["/absolute/path/to/piplapis-search-mcp/index.js"],
      "env": {
        "PIPL_API_KEY": "YOUR_PIPL_API_KEY"
      }
    }
  }
}

Replace /absolute/path/to/ with the actual path to the cloned repository and YOUR_PIPL_API_KEY with your Pipl API key.

Security

The API key is read from the PIPL_API_KEY environment variable and is never logged or exposed in tool outputs.

Use Cases​

Identity Lookup During Development​

While building onboarding, identity-enrichment, or investigation flows, ask your AI assistant to look up and connect real identity data without leaving the IDE:

"Search for jane.doe@company.com and check if the name matches Jane Doe in San Francisco"

The assistant calls search_by_email (or search_by_name with email), returns the matched identity, and you can immediately see whether the name, location, and other attributes align — all without writing a single API call.

Investigating Suspicious Users​

When reviewing flagged accounts or investigating fraud signals, pull up a complete identity profile in seconds:

"Look up the phone number +14155550123 and show me all associated social profiles"

The assistant calls search_by_phone, returns names, emails, addresses, social URLs, and more — giving you a full picture of the person behind the number.

Enriching Contact Data​

Enrich partial contact records by searching with what you have and getting back the full identity profile:

"I have a LinkedIn profile linkedin.com/in/johndoe — find the person's email and phone number"

The assistant calls search_by_url and returns all available identity data associated with that profile.

Resolving Ambiguous Matches​

When a search returns multiple candidates, use the search pointer to drill into a specific person:

"Search for John Smith in New York"

If the API returns several possible persons, you can follow up:

"Resolve the second candidate using their search pointer"

The assistant calls search_by_search_pointer to retrieve the full profile for that specific individual.

Bulk Testing & Validation​

Use the search_raw tool for flexible queries during testing, or search_by_person for structured multi-field searches:

"Search for a person with first name Clark, last name Kent, email clark.kent@example.com"

Free Test Query

Any query containing the email clark.kent@example.com is free and returns static example output — useful for testing your setup without consuming API credits.

Understanding Responses​

The Pipl Search API returns one of three outcomes:

  • Person Match — A single high-confidence person was found. This is a definitive match.
  • Possible Persons — Multiple candidates were found. Each includes a @search_pointer you can use with search_by_search_pointer to resolve a specific person.
  • No Match — No person found.
Important

A match score of 0 does not mean "no match" — it means the confidence level is undetermined (not enough data to rank). All returned possible persons are real candidates.

Resources​