SF Express MCP Server

A Model Context Protocol (MCP) server that provides integration with SF Express shipping and logistics APIs. This server enables LLM applications to interact with SF Express services for order management, shipment tracking, route queries, and logistics services.

Features

• Order Management: Create new shipping orders with comprehensive address and cargo information

• Shipment Tracking: Track packages using waybill numbers or order IDs with detailed route history

• Route Queries: Find available shipping routes between locations with pricing information

• Service Inquiry: Check service availability and restrictions between locations

• Logistics Services: Query warehousing, distribution, fulfillment, and return services

Supported SF Express APIs

This MCP server connects to the following SF Express API categories:

• Category 1, apiClassify 1: Order Creation (EXP_RECE_CREATE_ORDER)

• Category 1, apiClassify 2: Shipment Tracking (EXP_RECE_SEARCH_ORDER_RESP)

• Category 1, apiClassify 3: Route Queries (EXP_RECE_SEARCH_ROUTES)

• Category 1, apiClassify 4: Service Inquiry (EXP_RECE_SEARCH_SERVICE)

• Category 6, apiClassify 2: Logistics Services (EXP_RECE_SEARCH_LOGISTICS)

Installation

Prerequisites

• Node.js 18.0.0 or higher

• SF Express developer account and API credentials

Setup

1. Clone or download this project:

2. Install dependencies:

3. Configure environment variables:

Edit .env and fill in your SF Express API credentials:

4. Build the project:

Usage

Running the MCP Server

Start the server directly:

Or run in development mode:

Configuring with Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Using with npx

You can also run the server using npx (after publishing to npm):

Available Tools

1. sf_express_create_order

Create a new shipping order with SF Express.

Parameters:

• orderId (string): Unique customer order ID

• expressType (string): Service type (1-Standard, 2-Next Day, 3-Same Day, 4-Economic, 5-International)

• payMethod (string): Payment method (1-Sender pays, 2-Receiver pays, 3-Third party pays)

• custId (string): Customer ID from SF Express

• consigneeInfo (object): Recipient contact and address information

• deliverInfo (object): Sender contact and address information

• cargo (array): List of items to ship with quantities and weights

• addedService (array, optional): Additional services

• remark (string, optional): Special instructions

Example:

2. sf_express_track_shipment

Track shipment status and route history.

Parameters:

• trackingType (string): Type of tracking (1-waybill number, 2-order ID)

• trackingNumber (array): List of tracking numbers

• methodType (string, optional): Query method

Example:

3. sf_express_query_routes

Query available shipping routes and pricing.

Parameters:

• originCode (string): Origin area code

• destCode (string): Destination area code

• cargoWeight (number, optional): Cargo weight for pricing

Example:

4. sf_express_service_inquiry

Inquire about service availability between locations.

Parameters:

• originCode (string): Origin area code

• destCode (string): Destination area code

• serviceType (string, optional): Specific service type

Example:

5. sf_express_logistics_services

Query logistics services like warehousing and fulfillment.

Parameters:

• serviceType (string): Service type (warehouse, distribution, fulfillment, return)

• locationCode (string): Location code

• requirements (object, optional): Specific requirements

Example:

Error Handling

The server provides comprehensive error handling with structured error responses:

Common error codes:

• VALIDATION_ERROR: Invalid input parameters

• AUTHENTICATION_ERROR: Invalid API credentials

• NETWORK_ERROR: Network connectivity issues

• SERVICE_ERROR: SF Express API errors

• TIMEOUT_ERROR: Request timeout

Development

Project Structure

Building

Development Mode

Linting

Configuration

Environment variables:

Security Notes

• Never commit API credentials to version control

• Use environment variables for sensitive configuration

• Implement proper access controls in production environments

• Monitor API usage to prevent abuse

Troubleshooting

Common Issues

1. Authentication Failed: Check your API credentials

2. Network Timeout: Increase timeout or check network connectivity

3. Invalid Service Code: Ensure you're using the correct SF Express service codes

4. Rate Limiting: Implement proper rate limiting to avoid API limits

Debug Mode

Set environment variable for verbose logging:

License

MIT License - see LICENSE file for details.

Support

For SF Express API documentation and developer support:

• Developer Portal: https://open.sf-express.com

• API Documentation: https://open.sf-express.com/Api

For MCP protocol documentation:

• MCP Specification: https://modelcontextprotocol.io

• SDK Documentation: https://github.com/modelcontextprotocol

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Please ensure all tests pass and follow the existing code style.