SF Express MCP Server

How to use

You interact with the SF Express MCP Server through an MCP client by sending well-defined requests that map to SF Express API categories such as order creation, shipment tracking, route queries, service inquiries, and logistics services. Use the client to perform common workflows like creating a shipping order, tracking a package by waybill or order ID, pricing routes between locations, verifying service availability, and requesting warehousing or fulfillment services.

How to install

Prerequisites you need before installation:

• Node.js 18.0.0 or higher
• SF Express developer account and API credentials

Step-by-step installation flow:

• Clone or download the project
• Navigate into the project directory
• Install dependencies
• Configure environment variables with your SF Express credentials
• Build the project
• Run the server

# 1. Clone the project
git clone https://github.com/100kgforest/sf-express-mcp-server.git
cd sf-express-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env
# Edit .env and fill in your SF Express API credentials
# SF_EXPRESS_PARTNER_ID=your_partner_id_here
# SF_EXPRESS_REQUEST_ID=your_request_id_here
# SF_EXPRESS_CHECK_WORD=your_check_word_here

# 4. Build the project
npm run build

# 5. Start the server
npm start

Configuration and startup options

You can start the server directly or in development mode, and you have options to run it via npx for quick experimentation. The server relies on environment variables for SF Express credentials and optional timeout settings.

# Start in production mode
npm start

# Start in development mode
npm run dev

Using with Claude Desktop

To integrate with Claude Desktop, add a MCP server configuration that points to the local MCP server process. You can run the server locally and reference the runtime path in Claude Desktop’s config.

{
  "mcpServers": {
    "sf-express": {
      "command": "node",
      "args": ["/path/to/sf-express-mcp-server/dist/index.js"],
      "env": {
        "SF_EXPRESS_PARTNER_ID": "your_partner_id",
        "SF_EXPRESS_REQUEST_ID": "your_request_id",
        "SF_EXPRESS_CHECK_WORD": "your_check_word"
      }
    }
  }
}

Using with npx

You can also run the server using npx after publishing to npm.

npx sf-express-mcp-server

Available tools

The server exposes a set of tools to interact with SF Express APIs.

Error handling

The server returns structured error responses to help you diagnose issues quickly. Look for an error object with a code, message, and optional details and timestamp.

Development

Project structure and build steps are designed to support extendability and testing.

npm run build
npm run dev
npm run lint

Security and best practices

Protect API credentials by using environment variables, avoid committing secrets to version control, and implement proper access controls in production environments.

Troubleshooting

Common issues include authentication failures, network timeouts, incorrect service codes, and rate limiting. Verify credentials, network connectivity, and the correctness of endpoints.

sf_express_create_order

Create a new shipping order with SF Express using order, consignee, deliver, cargo, and optional services and remarks.

sf_express_track_shipment

Track shipment status and route history using a waybill number or order ID.

sf_express_query_routes

Query available shipping routes and pricing between origin and destination codes.

sf_express_service_inquiry

Inquire service availability between locations and optional service types.

sf_express_logistics_services

Query logistics services such as warehousing, distribution, fulfillment, and returns.