Mcp MCP Server

parseapi-mcp

Official ParseAPI MCP server. Look up places, addresses, companies, email, phone, weather, 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.

The shared hosted service remains on API 2.0. Installing this package selects API 2.1 for your local server without changing the shared service.

{
  "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@1.13.0"],
      "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. This version sends X-API-Version: 2.1.0 on every API tool request, matching its tool descriptions and SDK response types. The contract is fixed for local stdio and HTTP servers running this package, including retries. The shared hosted service remains on its existing API 2.0 release. Your key, OAuth identity and team's saved default stay the same. The API still accepts earlier Parse-Version request pins.

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.

ISO identifiers

Country uses iso_alpha3 and iso_numeric, State uses the full iso_subdivision code such as US-CA, Language uses iso_alpha3, and Currency uses iso_numeric. Primary country, state, language and currency codes keep their meaning. Results retain the selected API contract's exact keys, values, nulls and nesting. Earlier server contracts retain their earlier ISO spellings. Use the existing lookup methods for each resource.

Tools

Full mode provides 65 local lookup tools and 64 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, email, card, industry, industry_search, dns, asn, 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 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.

Time Deep includes resolution when a source wall time needs interpretation. 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 omit 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. 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 to each company result on paid plans in the same pooled request. Existing accounts retain their current Deep access. Selected website descriptions, logos, socials and founding claims are returned where available. Logo URLs are returned without fetching images. Directory tools do not accept lang. Empty listings do not establish private ownership. The company tool remains listed for compatibility, but national-number lookups are retired on the public API. Use company_search and company_id for maintained public-company records.

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 }.

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. Mini guides contain ordinary HTTP instructions; MCP keeps the tool policies and schemas. 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.

Bulk files

Agents can process a whole CSV using five tools in either catalog mode:

The agent needs a file-capable runtime. Transfer the CSV bytes directly to upload_url with upload_headers using HTTP PUT. Convert Excel or Numbers to CSV in that runtime first. Tool arguments contain file metadata and job IDs. They accept no file contents, base64, source URLs or server filesystem paths.

First call bulk_preview with the upload's id and no checks to confirm the completed upload and request analysis. Poll bulk_status until job.status is quoted. Then call bulk_preview, optionally passing checks, such as ["email", "phone", "ip"], to select operations present in the detected columns. Changing the selection requests analysis again. Repeat status and preview until the response includes a current quote. Inspect the sample and required setup before starting.

bulk_start requires that id, quote.id as quote_id and the user's approved max_cost_cents. Zero permits only zero additional cost. The server verifies the quote and ceiling. Paid jobs return a payment handoff when needed, and the tool does not charge a saved card. Keep the same job, quote and ceiling when recovering a start request. A lost create response must not trigger a blind second upload.

Fetch the finished download_url directly without an API key header. URLs expire and are private capabilities. File contents stay outside model context unless the user separately asks the agent to inspect them. Preserve the original columns and unknown answers in the customer's follow-up task.

Existing Bulk job URLs remain shareable. Treat job IDs and download URLs as file-access capabilities.

The existing API key or OAuth connection owns these jobs. The website origin can be configured with PARSEAPI_WEB_URL, independently of the lookup API origin.

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. Holiday and prove tools have no new language argument.

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.

Optional detail

Country Core contains the everyday reference: name, name_full, name_local, demonym, iso_alpha3 and iso_numeric country identifiers, continent, region and subregion, currency, calling code, flag, language and timezone codes, borders, bloc memberships and capital: { name, latitude, longitude }. Paid Deep adds specialist detail, including population, total area and national statistics. gdp_usd and gdp_per_capita_usd are current US dollars; population_growth_percent, urban_population_percent and internet_users_percent use a 0–100 percent scale (growth can be negative or exceed 100). GDP per person and these three percentages round once to two decimals in the API response. elevation_average is average terrain elevation in meters; lowest_point.elevation and highest_point.elevation keep their point-specific meaning. Unknown stays null and a known zero stays zero. Country tax references are grouped once as tax: { name, rate }; the rate remains a percentage. Read capital from the Core object and read optional tax references from tax.name and tax.rate on that same resource.

Country includes postal_format and postal_regex on every plan without requesting Deep. postal_format is an input hint based on one example, not a complete mask. postal_regex checks syntax, not whether a code exists or receives mail. Unavailable values are null.

Make the ordinary tool call. API 2.1 paid plans include their profile detail automatically; Free returns the complete everyday answer. Existing deep inputs remain supported for compatibility. Time, Date, Emoji, Phone, Point and Card offer optional detail on paid plans; existing accounts retain their current Deep access. Language includes every reference fact in Core, and Deep adds no fields. 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; only the source returns 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 a root tax object when the optional detail is available.

Stack API

Call the stack tool:

{"domain":"example.com"}

Stack checks static homepage HTML and response headers. It returns the checked URL, original checked_at time and eight technology arrays.

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. Unknown or conflicting versions are null. Detections describe the checked homepage.

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.1.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. 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.

Emoji catalog additions

Resolve Unicode emoji or a named shortcode, search or browse a bounded catalog, parse emoji positions in text, and convert between Unicode and a selected shortcode source. The ordinary lookup remains four fields:

GET /emoji/rocket

{"emoji":"🚀","name":"Rocket","shortcodes":[":rocket:","rocket"],"category":"Travel & Places"}

Paid plans include Unicode facts, keywords, tone families and available artwork automatically in API 2.1. Core values stay unchanged. Text parsing returns emojis with UTF-16 positions; conversion returns text and unresolved tokens with positions and reasons.

The compact JSON catalog contains offline identity, qualification-form and shortcode indexes. Use lang for localized names and keywords. Metadata and shared source notices are included in the catalog. Read an individual emoji with Deep for its artwork links. Artwork supports Google Noto, Twemoji and OpenMoji, with real SVG/PNG availability and immutable first-party URLs. A device's emoji font remains the ordinary display.

These additions are a local release candidate until the matching SDK and backend are published. Existing lookup and search contracts are preserved.

Canonical City operations

Classic lookup, search, nearest and named-nearby methods retain their default envelopes and required-field models. Browse uses cities and coordinate-nearby uses nearby, with nullable next_cursor (camelCase properties in Swift/Kotlin). Keep all query options unchanged when continuing a page; no client fetches pages automatically.

{"operation":"city_search","arguments":{"query":"Viena","format":"list","match":"fuzzy","max_distance":1}}

Each route retains its default response. Country inclusion/exclusion sets, timezone sets, inclusive population and meter-elevation bounds, stored-center bbox and signed multi-key sorting are available for collections. Unknown numeric facts do not match range filters.

Search defaults to prefix matching. Exact and fuzzy matching are explicit; fuzzy accepts maximum edit distance 1 or 2 and returns match evidence (type, source, value, language, edit_distance). Review a fuzzy choice before storing its ID.

Reviewed children, ancestors and siblings use canonical lists with partial relationship coverage. Empty data does not prove there are no geographic relatives. Children/siblings accept page controls; ancestors do not. Distance reports great-circle kilometers and miles between stored centers: zero is known zero, null is unknown, and it does not imply travel time or containment.

Strict ambiguity=error can return HTTP 409 ambiguous_city with up to two safe candidate identities. The existing error constructor and unrelated error metadata are preserved; candidates are retained only for that status/code and never contain Deep. GeoJSON is available through HTTP; these typed City list methods do not return GeoJSON.

Coverage by country and available fields is described at https://parseapi.com/city#coverage.

romanized=true requests reviewed official name forms as name_romanized and romanization_language (camelCase in Swift/Kotlin). Current reviewed forms cover 20 Japanese whole-city aliases in ja-Latn. Missing or conflicting forms stay null; ASCII folding is not substituted for an official form.

Conditional If-None-Match reads and GeoJSON currently use HTTP directly. A matching City ETag returns 304 without a body; ordinary billing and rate limits apply. These JSON client methods do not supply conditional-cache handling.

IP paid Deep includes supported approximate location, state_name, postal, latitude, longitude, timezone, routed network, asn_type and public proxy status. Missing facts remain null. Coordinates describe range geography, not device GPS. asn_type classifies the origin network, not subscriber connection technology. Proxy/VPN false means unlisted. Optional fields are omitted without the requested detail or access.

Capital coordinate migration

Country and State capital coordinates use latitude and longitude. Update capital.lat and capital.lon reads to capital.latitude and capital.longitude when adopting this release.

Postal and Weather response corrections

In API 2.1, Postal property_tax contains annual_median; tax is grouped under tax with name, rate and component rates. Weather minute rows use precipitation_rate (mm/h) and precipitation_rate_in (in/h). Historical history.precipitation and precipitation_in remain daily totals. Unavailable Weather collections remain null; a known empty collection remains []. MCP returns these API values unchanged. Existing clients reading the earlier minute keys must update those reads when using current API 2.1.0; frozen 1.0.0 is preserved.

API 2.1 upgrade

API 2.1 Time returns the clock first and the matched place in location. Read that place directly; location.candidates is for unresolved choices. Unused resolution is absent. City matches keep the match kind, text and language without the source category or spelling score. Holiday JSON keeps scope and completeness without calendar hashes; explicitly selected work-profile pins remain.

This client targets ParseAPI 2.1.0. Upgrading requires response-reader changes: optional detail now lives on its resource. Read population instead of deep.population. Deep remains an explicit request for optional detail. Without the request or access, optional fields are absent. A returned null still means unknown. User-Agent device, OS and browser are objects in every mode. Postal tax is one tax object. Specialist Weather measurements live in current. Metered Carrier and HLR return the complete purchased result without a Deep switch.

Use the email_verify tool for mailbox verification. It sends POST /email/verify with { "email": "person@example.com" } and defaults to no automatic retries. The earlier Email deep argument is accepted only as a migration alias for that same operation. App keys receive permission_denied. Bulk exports retain their existing column names and saved-job recovery.

The 2.0 API is a temporary migration bridge for older installed clients. There is one maintained SDK line using the 2.1 structure.

Upgrade to API 2.1

This version selects API 2.1.0. Update existing .deep property reads to the fields at their natural homes, such as country.population. User-Agent identities are objects; Postal tax and Weather observations keep their documented object homes. Paid profile detail is automatic in API 2.1. Existing explicit depth requests remain supported; verification stays explicit.

This minor version changes existing field reads. Upgrade the SDK and your application reads together. Existing factories remain. Email verification is explicit and includes basic validation; Carrier/HLR need no extra detail request. Preserve missing values, null, false and 0.