parseapi-mcp

Official ParseAPI MCP server. Look up places, addresses, company numbers, email, phone, weather, currency, timezones, dates and more from your AI agent.

Hosted

One URL, nothing to install. Add the server and sign in once in the browser. Free plan works.

{
  "mcpServers": {
    "parseAPI": { "url": "https://mcp.parseapi.com" }
  }
}

Cursor: Add to Cursor

Repo-root .mcp.json is keyless on purpose. cursor.directory auto-detects it when you submit or refresh the listing.

CI and headless setups skip the browser with a key from parseapi.com:

{
  "mcpServers": {
    "parseAPI": {
      "url": "https://mcp.parseapi.com",
      "headers": { "X-API-Key": "your-api-key" }
    }
  }
}

Local

{
  "mcpServers": {
    "parseAPI": {
      "command": "npx",
      "args": ["-y", "parseapi-mcp"],
      "env": { "PARSEAPI_KEY": "your-api-key" }
    }
  }
}

API versions

Since version 1.0.0, the package explicitly selects the API contract supported by this MCP package. Every API tool request sends Parse-Version: 2.0.0, matching this release's tool descriptions and SDK response types. The contract is fixed for both local stdio and hosted HTTP, including retries. Your key, OAuth identity and team's saved default stay the same.

For local stdio, pin the MCP package version in your application configuration and test the new release before deploying it. A future major MCP upgrade can select a newer API contract. There is no version argument to add to individual tool calls. The hosted service uses the API contract supported by its deployed MCP release.

MCP packages older than 1.0.0 keep their existing behavior and use the team's default. Keep that default unchanged while older applications depend on it. Rolling back to a package without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged. See API versions and migration.

Tools

Full mode provides 68 local lookup tools and 67 hosted lookup tools, plus discover for local metadata and preflight for authenticated task estimates. ip_self is local only. time returns current local time and Unix seconds. It accepts a timezone or coordinates and defaults to UTC when both are omitted. date parses the supplied date, or returns today in UTC when omitted. Existing timezone calls remain supported with their original arguments. Every lookup returns the JSON the API serves.

Tools follow the lookup names: country_states, city_search, postal_nearby, address, address_search, company, company_id, company_search, company_coverage, email, vat, bank, bank_us_ach, bank_requirements, card, provider, vehicle, industry, industry_search, tariff, dns, asn, mac, currency_rate, and the rest. Text searches take query. Company directory search supports one name/domain/ticker/identifier selector or country/exact-SIC discovery filters.

The existing naics and naics_search tools remain available as compatibility names for Industry.

Industry paid deep records include classification deep.exclusions, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include match: the matched field (name, term or naics) and text, plus corrections with from and to tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit match. Older responses may omit it.

Example tool arguments:

Time uses disambiguation only for offsetless at with to or targets. The default compatible selects the earlier repeated time or advances a skipped time. earlier and later choose the respective instant. reject returns ambiguous_time for repeated times and nonexistent_time for skipped times. Prefer it for user-entered appointments. Ask for an explicit offset or the user's choice before retrying a rejected local time. Explicit offsets select an instant directly. Time deep is available in the same pooled request on every plan.

Canonical Time source deep includes timezone_database_version and nullable resolution. Resolution reports kind (unique, overlap or gap), policy, signed adjustment_seconds, and chronological alternatives with exact local at, Unix seconds and UTC offset. Unique wall times have no alternatives. Explicit-offset timestamps, current clocks, non-conversion lookups and unknown source zones have null resolution.

Elevation accepts exactly one of lat and lon, points, or path with samples. A point list supports up to 512 coordinates as lat,lon pairs separated by |, or enc: followed by a Google encoded polyline, with at most 12000 characters. The points response array preserves input order and duplicate coordinates. Each sample includes meters, feet and grid resolution in meters. Unknown samples stay null. A list uses one pooled request, with JSON POST selected automatically for long URLs.

A path uses the same string formats with 2-512 vertices and a required integer samples count from 2 to 512. The response points include both endpoints, spaced uniformly by cumulative great-circle distance along the path. Each segment follows the shortest arc. A segment with antipodal endpoints is rejected because it does not define a unique arc. A path uses one pooled request. samples is invalid with a single coordinate or a point list.

Australian postal lookup returns core localities with suburb choices (city, state, state_name). Null or an omitted field means unknown, while [] means the reviewed reference has no eligible choices. A single choice can coexist with city: null. Ask for the user's suburb choice and preserve manual entry. These are geographic choices, not mailing-address verification. AU Postal tool results include a separate source notice after the JSON. G-NAF source, adaptations and licence.

Address lookup returns standardized components and registration status for the US and France. Its deep object is currently empty. National-number company lookup returns validity, registration status and business details when available. address_search also accepts postal and ip to narrow or rank matches. French search needs country: "FR" and either postal or city.

For the company directory, call company_search with at most one of query, domain, ticker or identifier. Use exchange with a ticker and authority with an identifier. Review the candidates, then pass the chosen id to company_id. Send the returned next as cursor with the same selector, filters and limit for another page. Directory deep adds detail in the same pooled request on every plan and belongs to each company result. Selected website descriptions, logos, socials and founding claims include field-level sources. Logo URLs are returned without fetching images. Directory tools do not accept lang. company_coverage describes the edition's records, and empty listings do not establish private ownership. The existing company tool continues to parse national registration numbers.

For discovery without an identity selector, supply country or both industry and industry_type. For example: { "country": "US", "industry": "0700", "industry_type": "sic" }. SIC is the supported namespace; its exact four-digit code stays a string. Empty requests, incomplete industry pairs and multiple selectors are rejected. Country means the profile country. Filters intersect, unknown values do not match, and the same filters and limit must accompany a returned cursor. Filter-only candidates carry match: { "field": "filters", "value": null }.

Paid Deep also returns taxonomies in published order, with taxonomy code, specialty label, primary flag and provider-reported license number/state, plus enumerated_at, updated_at and reactivated_at record dates. Reported licenses are not verified licenses. Null lists mean unavailable; empty lists mean the edition contains no entries. Core sources is available on every plan: NPPES, LEIE, PECOS and opt-out each have nullable edition metadata (edition, published_at, through, imported_at). Provider record dates are separate from source publication and completed import dates. Older responses may omit these additions. Edition details remain null until a verified source is served.

Pass the original NPI as a string. valid checks its format and checksum; registered means a match in the stored NPPES snapshot. active reflects recorded NPI deactivation, not licensure. excluded is an NPI-only OIG LEIE match; false is not a complete exclusion clearance. These directory facts do not verify credentials, current practice contact or payment eligibility.

Invalid input returns valid: false with unknown provider fields. A checksum-valid number missing from the snapshot returns registered: false; unavailable storage remains an API error. Preserve null as unknown.

The default pooled lookup includes provider identity, specialty and practice contact where held. Paid deep adds deactivated_at, medicare, opt_out and enrollments from stored source files, with no separate check meter or live verification. enrollments: null means unavailable; [] means no enrollment rows are returned. The API omits unrequested deep and returns {} when requested on Free.

Ordinary lookups retry up to twice after a transient failure. A valid Retry-After is honored when the wait is at most five seconds; longer waits return the API error immediately without retrying early. When the response supplies this header, the error includes retry_after with its original seconds or HTTP-date value. Metered lookups and address deep checks default to no retries. Cancelling a tool call cancels the pending SDK request.

Errors come back as JSON with a machine-readable code. Branch on code, never on message text. A miss is not_found. No key is invalid_api_key.

Agent discovery

Ask discover what an operation can determine before making a lookup:

{ "operation": "email" }

The result includes the actual input schema and reviewed policies for capabilities, freshness, uncertainty, billing units, credential types and retries. Both JSON text and MCP structuredContent carry the same result. Email, Domain, DNS, MX, Country, Time and timezone discovery have reviewed policies. Other operations return their input schema with policy: null. Field meanings are specific to each operation. An unknown result is not automatically a reason to retry.

Use { "query": "mailbox" } to find operations. Search returns up to five summaries by default. detail: "full" includes schemas and policies. Use limit and the returned next_offset to page through results. Metadata calls make no API requests and consume no lookup units. Hosted HTTP still requires its existing authentication before discovery.

Policies describe the API contract. effective_access: "not_evaluated" and pricing: "not_quoted" mean discovery has not inspected the credential's permissions, remaining allowances or accepted rates. Use preflight for those account-specific estimates. A read-only lookup can still consume a paid unit.

Call preflight with a secret key and operation counts before spending:

{
  "operations": [{ "operation": "email", "count": 100, "deep": true }],
  "budget_usd": "2.50"
}

Preflight supports Email, Domain, DNS, MX and Country, with up to 20 rows and 100,000 total lookups. It needs no lookup inputs or personal data. Check permitted, cost.status, capacity and budget.within_maximum together. Monetary values are decimal strings. The maximum assumes included Email checks are exhausted. The projection uses currently unallocated included checks. Unknowns stay null. Both use the credential's accepted rates.

The estimate allows up to three attempts per ordinary lookup and one per Email Deep lookup. Extra calls or retries require a new estimate. Capacity can change with concurrent work. Preflight reserves no units or money, performs no paid checks, and does not enforce the supplied budget. It uses the normal request rate limit. Subscription fees, tax and model costs are excluded. Preflight uses API contract 2.0.0 and the matching JavaScript SDK 1.2.0 or later.

For a compact tool catalog, set PARSEAPI_MCP_MODE=compact on the MCP process:

PARSEAPI_MCP_MODE=compact npx -y parseapi-mcp@1.6.0

Set PARSEAPI_KEY in the process environment for lookups. Compact mode advertises three tools, discover, preflight and lookup. After discovering an operation, pass its exact name and arguments:

{ "operation": "country", "arguments": { "code": "US" } }

lookup uses the same input validation, cancellation, version pin, SDK and billing behavior as the named tools. It executes one operation and cannot run arbitrary code or request arbitrary URLs. Full mode is the default and preserves existing named lookup calls. The same process setting supports self-hosted HTTP.

The policy source is the API's src/route/help/agent-catalog.json. Current API help exposes the same metadata as agent. Frozen API 1.0.0 help stays unchanged. In a ParseAPI workspace, run npm run catalog:sync to copy a reviewed policy change, then npm run catalog:check. An independent checkout can pass -- --source /path/to/api. Package builds use the checked-in copy and do not need the API checkout or a network request.

Display language

This source candidate adds optional lang to supported tools. For example, country accepts {"code":"DE","lang":"fr"}. It requires a matching API localization release, data, and JS SDK package; installing the existing published package does not activate it.

Display names follow available source translations. IDs, native-name fields, numbers and input parsing stay unchanged. Omitted language keeps the default behavior. Measure parsing, currency rates, Holiday and prove tools have no new language argument.

Measurements

Call measure with { "measure": "5 ft 11 in", "to": "cm" }. The result keeps the amount as the decimal string "180.34". Without to, the result uses the canonical unit for its type. Optional locale and system (us or imperial) resolve explicit number or customary-unit ambiguity.

Call measure_units with { "unit": "m" } to discover compatible targets, or {} for the reviewed catalog. Optional query and type filters narrow the list. Ambiguous input remains a successful result with valid: false, reason, and choices. Invalid targets return the ordinary API error. Both tools use pooled requests.

Development

npm install
npm run typecheck
npm test          # builds and tests with mocked fetch and in-memory MCP
npm run eval:agents # offline benchmark self-test, no model or live API calls
npm run smoke     # stdio + http, includes live API authentication checks
npm run serve     # http on :8080

Offline tests pin the public tool names and argument schemas in test/public-api.json, exercise every operation and query option, and verify errors, retries and cancellation. Review baseline changes as public API changes. Publishing runs typecheck and offline tests first.

The agent benchmark compares full and compact discovery on fixed tasks with synthetic API responses. Its scripted reference run verifies the harness and grading, not agent completion quality. Model tokens and cost remain null until an adapter supplies measured usage. Fixture billing is simulated and always labeled separately from live charges.

MIT licensed.

Bank returns core checks for input, country, length, structure, checksum and national rules, plus an issues list. States are passed, failed, not_checked or not_supported. Unsupported national checking is not a failure. valid covers the implemented format and checksum rules, not account existence, ownership or payment reachability. Directory names and BICs may be null independently. Older responses may omit checks and issues, and future states and issue codes remain strings. Pass the original input unchanged so the API can report invalid characters. Deep account remains the BBAN remainder.

Optional detail

Start with the default tool call. Use the same tool with deep: true for richer facts. Time, Date, Currency, Language, Emoji, Phone, Bank and Point include detail on every plan. Geographic profiles, Name evidence and NAICS definitions require a paid plan. Carrier and HLR detail stays inside the same metered core unit, including Free allowance units, with no additional charge or second gate.

Search detail belongs to each returned entity. Time conversion puts target display detail in to.deep; only the source returns deep.next_dst. Name core parsing needs no dictionary lookup. Paid Name deep also returns flat short, directory, and initials. Optional name_locale selects CLDR formatting rules, defaults to en, and leaves parsing and gender context unchanged. Unavailable formatting is null, and older responses may omit these fields. Country, State and Postal tax references are in their paid deep bags.

Stack API

Call the stack tool:

{"domain":"example.com"}

Pass a public hostname without a scheme, path, port or IP address. Stack returns the checked URL and checked_at time, followed by scope, pages and partial. scope is homepage or site; pages counts successfully checked HTML pages. partial is true for homepage-only or incomplete bounded site checks. False means the known in-scope candidates were completed, not that every page on a website was visited. A homepage result has scope: "homepage", pages: 1 and partial: true.

cms, servers, frameworks, ecommerce, analytics, chat, payments and hosting are arrays because a site can use several technologies in each category. Each entry contains technology, name and nullable version. Technology codes are open strings. A successful check uses empty arrays for categories with no matches. When no HTML page could be checked, checked_at and all categories are null, pages is 0 and partial is null. Unknown or conflicting versions are null. Missing detections do not prove absence.

Successful checks may be reused for up to 24 hours. pretty optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.0.0 selected by this client.

The stack tool allows 35 seconds per attempt for a first check. MCP cancellation still aborts the request.

Time targets accepts 1-10 destination IDs instead of to. Results retain the requested order and duplicates at one instant in a single pooled request. Unknown source coordinates return targets: null. Unknown destination IDs return not_found for the whole request. Use time_zones to search serving IDs or omit its query for the complete sorted list and pinned rule edition. An empty search result is timezones: [].

time accepts one explicit IP, city, country, IATA airport, ICAO airport, port UN/LOCODE or address input. Country/state may narrow city or address. Address point lookup currently requires US country context. Port reference coverage is a reviewed subset of UN/LOCODE. Hosted calls never infer the user's IP from the server. Ambiguous or missing inputs return null clock fields and location candidates. Ask for the missing context or let the user choose rather than selecting a candidate silently.

time_zones can filter by country, IANA area, exact offset, abbreviation, DST at an instant or DST occurrence during the UTC calendar year. It preserves explicit false filters. details adds rich rows and the common evaluation instant, while the default identifier list remains compact. Abbreviations return candidate zones. Source deep exposes standard and signed seasonal offsets plus actual DST-season transition boundaries. Negative seasonal adjustments and null boundaries retain their meaning.

Bank tools send original IBAN, routing and account strings in POST JSON bodies, keeping account input out of URLs. bank retains optional country and deep controls. Deep directory evidence identifies the immutable source edition and actual match grain when a directory lookup ran; it does not prove country completeness or reachability. bank_us_ach takes routing/account strings and checks the ABA routing checksum plus account-field syntax. It has no deep option and cannot verify an account checksum, existence, ownership or ACH eligibility. Preserve all account characters and leading zeros. bank_requirements takes a country and optional format (iban by default, or us_ach) and returns accepted fields, check scope and limitations. Requirements are metadata, not bank coverage. Avoid logging tool arguments or request bodies containing banking input.

When US ACH returns a bank name, MCP includes a separate routing reference attribution notice alongside the unchanged JSON result.

Vehicle lookups use vin as the input and response field. The vin tool remains available for compatibility.