Skip to main content
Glama
oliverames

Parcel MCP Server

by oliverames
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

Parcel MCP Server

CI npm

An MCP server for Parcel delivery tracking. It covers every field and operation in Parcel's documented external API, provides the daily carrier catalog, and runs through local stdio or a hosted Cloudflare remote connector.

This project is not affiliated with Ivan Pavlov or Parcel.

Coverage

Parcel API

MCP tools

GET /external/deliveries/ with active and recent

parcel_list_deliveries, parcel_get_delivery

POST /external/add-delivery/ with all seven request fields

parcel_add_delivery

GET /external/supported_carriers.json

parcel_list_carriers, parcel_find_carriers

Parcel does not document edit, delete, archive, or forced-refresh endpoints. This server does not claim those capabilities.

Related MCP server: Parcel MCP Server

Tools

  • parcel_auth_status reports credential discovery and the write gate without an API call.

  • parcel_list_deliveries returns every delivery and event from the active or recent API view.

  • parcel_get_delivery selects one exact tracking number from those API views.

  • parcel_list_carriers returns the complete carrier code map.

  • parcel_find_carriers searches carrier names and codes.

  • parcel_add_delivery submits one delivery and supports tracking_number, carrier_code, description, language, send_push_confirmation, postcode, and email.

The add tool is not advertised unless PARCEL_ALLOW_WRITES=1. This prevents an MCP client from invoking a write when the server was intended to be read-only.

Parcel API limits

  • Parcel Premium is required.

  • Delivery reads return cached data and do not trigger a carrier refresh.

  • Reads are limited to 20 requests per hour.

  • Adds are limited to 20 requests per day, including failed requests.

  • The add endpoint accepts one delivery per request.

  • Newly added deliveries can show no data until Parcel's next server update.

Local installation

Generate an API key at Parcel Web Access, then use one of these credential methods:

export PARCEL_API_KEY="your-parcel-api-key"
export PARCEL_ALLOW_WRITES=1
npx -y @oliverames/mcp-server-for-parcel@latest

The server also supports:

  • PARCEL_API_KEY_FILE, a small file containing only the key.

  • PARCEL_OP_PATH, an op:// reference read through the 1Password CLI.

  • Codex ~/.codex/config.toml and Claude ~/.claude/settings.json environment sections.

Credential priority is the process environment, host configuration, key file, then 1Password. The server never sends the key outside https://api.parcel.app and refuses redirects.

Claude Desktop, Claude Code, Codex, Hermes, and Antigravity

The repository includes native manifests for each host. The generic configuration is:

{
  "mcpServers": {
    "parcel-mcp-server": {
      "command": "npx",
      "args": ["-y", "@oliverames/mcp-server-for-parcel@latest"],
      "env": {
        "PARCEL_API_KEY": "${PARCEL_API_KEY}",
        "PARCEL_OP_PATH": "${PARCEL_OP_PATH}",
        "PARCEL_ALLOW_WRITES": "1"
      }
    }
  }
}

Leave PARCEL_ALLOW_WRITES empty for a read-only server.

Hosted Cloudflare connector

The worker/ directory provides an OAuth 2.1 protected Streamable HTTP endpoint at https://parcel.amesvt.com/mcp, plus legacy SSE for older clients. During authorization, the connector asks for a Parcel API key, validates it against Parcel, encrypts it with AES-GCM, and stores it per connection. The key never enters the connector's OAuth token or MCP Durable Object state.

The connector supports PKCE S256, dynamic client registration, optional write access, origin filtering, separate consent-signing and data-encryption keys, encrypted key deletion, and security headers. See the deployment guide.

The production deployment at parcel.amesvt.com is private. Cloudflare stores an allowlist containing only the SHA-256 hash of Oliver Ames' Parcel API key, so authorization attempts using any other Parcel key are rejected.

Development and verification

npm install
npm test
npm run smoke:list-tools
npm run smoke:live-tool
npm run smoke:packed
npm run release:check
npm pack --dry-run

The packed-install test installs the actual tarball and launches both declared bin names through npm's relative symlinks. CI tests Node 18, 20, and 22, audits dependencies, scans secrets, and tests the Worker.

Security and privacy

See SECURITY.md and the hosted connector privacy notice. Do not commit Parcel API keys. If one is exposed, revoke it through Parcel Web Access and generate a replacement.

License

MIT. Copyright 2026 Oliver Ames.

Available Tools

5 tools
parcel_auth_statusParcel Authentication StatusA
Read-onlyIdempotent

Inspect Parcel credential discovery and write-tool availability without calling Parcel.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the valuable behavioral detail that the tool does not make an external call to Parcel, which is beyond what the annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 10 words, front-loaded and free of unnecessary detail. Every word contributes to understanding the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no parameters and no output schema, the description fully conveys its purpose, scope, and safety profile. The annotations complement the text, and no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is empty. Since there are no parameters to document, the baseline of 4 applies and the description does not need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the verb 'Inspect' and precisely identifies the resource: Parcel credential discovery and write-tool availability. This clearly distinguishes it from sibling tools like parcel_list_deliveries or parcel_get_delivery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without calling Parcel' provides clear context that this is a safe preflight check for credential status. However, it does not explicitly name alternative tools or when not to use it, so it falls short of full usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parcel_find_carriersFind Parcel CarriersA
Read-onlyIdempotent

Search the complete Parcel carrier catalog by code or display name before adding a delivery.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
response_formatNomarkdown

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=true, openWorld=true, idempotent=true, and destructive=false, so safety is covered. The description adds value by specifying the search scope ('complete catalog') and the search keys (code/display name), plus a workflow hint. It does not discuss output format or pagination, but with annotations present, this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no fluff. Every phrase contributes meaning: action, resource, search criteria, and workflow context. No redundant or extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only search tool with rich annotations and schema, the description provides sufficient purpose and usage context. It could be more complete by explicitly naming the alternative sibling tool or describing the response format, but the current description is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does explain the 'query' parameter implicitly by saying the search is by code or display name. However, 'limit' and 'response_format' are not elaborated; they are somewhat self-explanatory but the description does not fully carry the burden for all parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific language: 'Search the complete Parcel carrier catalog by code or display name before adding a delivery.' This clearly identifies the action (search), the resource (catalog), the scope (complete), and the search criteria (code/display name). It also distinguishes itself from sibling list_carriers by focusing on searching rather than listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context: 'before adding a delivery.' This implies the tool should be used as a prerequisite step. However, it does not explicitly contrast with parcel_list_carriers (the sibling that lists carriers) or state when to use one over the other, so it lacks exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parcel_get_deliveryGet Parcel DeliveryA
Read-onlyIdempotent

Find one delivery by exact tracking number within Parcel's active or recent API response and return all of its cached events.

ParametersJSON Schema
NameRequiredDescriptionDefault
filter_modeNorecent
response_formatNomarkdown
tracking_numberYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context that events are 'cached' and limited to 'active or recent' API response, which informs the user about data freshness and scope. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that is wholly informative; no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter tool with no output schema, the description covers the action, target, and return value. It does not explain the impact of filter_mode and response_format, but the schema supplies those defaults. The description gives enough context for a straightforward use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description clarifies the purpose of 'tracking_number' by emphasizing exact match, and hints at 'filter_mode' via 'active or recent'. However, it provides no guidance on 'response_format' default or alternatives, leaving the schema enums to carry that meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Find' and identifies the resource as 'one delivery' via 'exact tracking number', with the outcome 'return all of its cached events'. This clearly differentiates from sibling 'parcel_list_deliveries' which lists multiple deliveries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly conveys that this tool is for locating a specific delivery when the exact tracking number is known, distinguishing it from listing tools. However, it does not explicitly state when not to use it or mention alternative tools by name, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parcel_list_carriersList Parcel CarriersA
Read-onlyIdempotent

Return the complete, daily-updated map of Parcel carrier codes to names. This covers GET /external/supported_carriers.json and requires no API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
response_formatNomarkdown

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool safe (readOnly, non-destructive, idempotent). The description adds behavioral context beyond that: the data is 'daily-updated' (so results change over time) and 'requires no API key' (auth simplicity). It also cites the exact GET endpoint, providing transparency about what operation is performed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary purpose, no filler. Every word earns its place: purpose, update frequency, scope, endpoint, and auth requirement are all covered efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one optional param, no output schema), the description is complete. It explains the return value (map of codes to names), the data freshness, the endpoint, and auth requirements. Annotations cover safety, so there are no significant missing details for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one optional parameter (response_format) with an enum and default, which is self-explanatory. The description does not mention this parameter, but the schema already conveys its meaning. While schema description coverage is 0%, the simple enum-based param does not require additional explanation, so the description adds no specific parameter semantics but does not create a gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Return the complete, daily-updated map of Parcel carrier codes to names,' which is a specific verb+resource with scope. It also distinguishes from siblings like find_carriers by emphasizing completeness and daily updates, and names the endpoint, leaving no ambiguity about what it does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context—this returns a complete, daily-updated mapping and requires no API key—so an agent knows when to use it for a full list. It does not explicitly exclude alternatives like find_carriers, but the scope is well-defined, giving sufficient guidance without needing explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parcel_list_deliveriesList Parcel DeliveriesA
Read-onlyIdempotent

Return Parcel's complete recent or active delivery list, including status, expected dates, and every cached carrier event. This covers GET /external/deliveries/.

ParametersJSON Schema
NameRequiredDescriptionDefault
filter_modeNoactive returns upcoming deliveries; recent also includes recently completed deliveriesrecent
response_formatNomarkdown

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond annotations by specifying the scope ('complete... list'), the included fields ('status, expected dates, and every cached carrier event'), and the underlying endpoint. It does not contradict annotations, and the extra details about data richness provide meaningful transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and contains no filler. Every phrase adds value: the completeness, the included data types, and the endpoint coverage. It is appropriately sized for a tool with only two simple parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 2 simple parameters, no output schema, and strong annotations. The description explains what the tool returns (delivery list with status, dates, events) but does not clarify the output format (markdown vs json), default behavior of filter_mode, or any pagination/ordering. Given the simplicity, a moderate score is warranted—it covers the basics but leaves some usage-relevant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: 'filter_mode' has a description, but 'response_format' lacks one. The tool description does not compensate for this gap; it mentions 'recent or active' which aligns with filter_mode but does not explain how to set it or introduce the response_format parameter. With the schema leaving one parameter undocumented and the description providing no parameter-level detail, the semantics are weak.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Return'), a resource ('Parcel's complete recent or active delivery list'), and the content ('status, expected dates, and every cached carrier event'). It inherently distinguishes from sibling tools like 'parcel_get_delivery' which targets a single delivery, and 'parcel_list_carriers' which lists carriers. The endpoint reference 'GET /external/deliveries/' reinforces the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via 'recent or active delivery list' and 'complete' but does not explicitly state when to choose this instead of alternatives, nor does it mention exclusions like filtering or pagination. Unlike an ideal case with explicit alternative references, the guidance here is only implicit, leaving the agent to infer the tool's role from the name and context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv1.0.0
    • First observedparcel_auth_status
    • First observedparcel_find_carriers
    • First observedparcel_get_delivery
    • First observedparcel_list_carriers
    • First observedparcel_list_deliveries
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool addresses a distinct concern: authentication status, listing deliveries, fetching a single delivery, listing carriers, and searching carriers. There is no overlap in purpose or output type.

Naming Consistency4/5

All tools share the parcel_ prefix and use snake_case. Most follow a verb_noun structure (list_deliveries, get_delivery, list_carriers, find_carriers), but parcel_auth_status is a noun phrase rather than verb_noun, creating a minor deviation from the otherwise consistent pattern.

Tool Count5/5

With 5 tools, the server is well-scoped for its domain of Parcel delivery and carrier lookups. Each tool serves a clear purpose, and the count is within the recommended range for a focused integration.

Completeness3/5

The read-side surface is well covered (list/get deliveries, list/search carriers), but the mention of 'adding a delivery' in find_carriers implies a write operation that is missing. There is no add_delivery or remove_delivery tool, leaving an incomplete lifecycle.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Parcel Tracking MCP Server

    iamfiro
    A
    license
    B
    quality
    D
    maintenance
    Allows tracking of parcel deliveries across various carriers using the 17track.net API, with automatic or manual carrier detection.
    2
    21
    6
    MIT

  • Parcel MCP Server

    NOVA-3951
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to track and manage deliveries by interacting with the Parcel delivery tracking API. Users can add new shipments, retrieve active delivery statuses, and look up carrier information through natural language.
    2
    -

  • Parcel App MCP Server

    as-j
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables users to manage package deliveries through the Parcel.app tracking API. It allows AI clients to list active or recent deliveries and add new packages directly to a Parcel account using tracking numbers and carrier codes.
    21
    GPL 3.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oliverames/parcel-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server