Parcel Tracking MCP

🚀 Parcel Tracking MCP Server

A Model Context Protocol (MCP) server for tracking parcel deliveries using the 17track.net API.

🚀 Quick Start

This server enables you to track parcel deliveries using the 17track.net API. It supports various carriers and offers automatic carrier detection.

✨ Features

• Track parcel deliveries from various carriers
• Automatic carrier detection
• Support for manual carrier specification
• Built with TypeScript and MCP SDK

📦 Installation

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• 17track.net API token

Install the Package

Install the package via npm:

npm install -g parcel-tracking-mcp-server

Or install locally:

npm install parcel-tracking-mcp-server

🛠️ Configuration

Create a config.json file in your working directory with your 17track.net API token:

{
  "apiToken": "your-17track-api-token-here"
}

⚠️ Important Note

The server looks for config.json in the current working directory where you run the command.

Getting a 17track.net API Token

1. Visit 17track.net
2. Sign up for an account
3. Navigate to the API section
4. Generate your API token
5. Add it to your config.json file

💻 Usage Examples

Running the Server

If installed globally:

parcel-tracking-mcp-server

If installed locally:

npx parcel-tracking-mcp-server

Or if you're using it as a dependency in your project:

node node_modules/parcel-tracking-mcp-server/dist/index.js

MCP Client Configuration

To use this server with MCP clients (like Claude Desktop), add it to your MCP configuration:

{
  "mcpServers": {
    "parcel-tracking": {
      "command": "npx",
      "args": ["parcel-tracking-mcp-server"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "parcel-tracking": {
      "command": "parcel-tracking-mcp-server"
    }
  }
}

Available Tools

tracking-delivery

Track a parcel delivery by providing a tracking number.

Parameters:

• number (required): The tracking number of the parcel
• carrier (optional): The carrier of the parcel (defaults to 'auto' for automatic detection)

Example:

// Track with automatic carrier detection
await trackingDelivery({
  number: "1234567890"
});

// Track with specific carrier
await trackingDelivery({
  number: "1234567890",
  carrier: "ups"
});

Supported Carriers

The server supports automatic carrier detection, but you can also specify carriers manually. Common carriers include:

• UPS
• FedEx
• DHL
• USPS
• China Post
• And many more (check 17track.net documentation for full list)

📚 Documentation

API Response Format

The server returns tracking information in JSON format, including:

• Tracking status
• Delivery progress
• Timestamps
• Location updates
• Carrier information

Error Handling

The server includes comprehensive error handling:

• API connection errors
• Invalid tracking numbers
• Missing configuration
• Network timeouts

🔧 Technical Details

Project Structure

├── index.ts          # Main server implementation
├── config.json       # Configuration file (create this)
├── package.json      # Dependencies and scripts
└── README.md         # This file

Dependencies

• @modelcontextprotocol/sdk - MCP SDK for building servers
• zod - Schema validation
• node-fetch - HTTP requests (if needed for older Node.js versions)

📄 License

MIT License

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

🆘 Support

For issues related to:

• MCP protocol: Check the MCP documentation
• 17track.net API: Visit 17track.net API docs
• This implementation: Create an issue in the repository

📜 Changelog

v1.0.0

• Initial release
• Basic parcel tracking functionality
• Support for automatic and manual carrier detection
• Error handling and logging