usps-mcp-server

bailur/usps-mcp-server

3.2

If you are the rightful owner of usps-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The USPS Address Validation and Standardization MCP Server is a Model Context Protocol server designed to provide AI assistants with tools to interact with USPS services, specifically for address validation and standardization.

Tools
1
Resources
0
Prompts
0

USPS Address Validation and Standardization MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with tools to interact with USPS services, specifically address validation and standardization.

Features

  • Address Validation: Validate and standardize US addresses using the official USPS Address Validation API
  • OAuth2 Authentication: Secure authentication using USPS OAuth2 Client Credentials flow
  • MCP Protocol Compliance: Standard MCP server implementation for AI model integration
  • Comprehensive Error Handling: Robust error handling for API timeouts, rate limits, and validation errors
  • TypeScript Support: Full TypeScript implementation with type safety

Prerequisites

  1. USPS Business Account: You need a USPS Business Account to access the APIs. Read the Getting Started at USPS Developer Portal
  2. API Credentials: Obtain Consumer Key and Consumer Secret from your API app

Setup

1. Clone and Install

git clone https://github.com/bailur/usps-mcp-server.git
cd usps-mcp-server
npm install

2. Environment Configuration

Copy the example environment file and configure your USPS credentials:

cp .env.example .env

Edit .env with your USPS API credentials:

USPS_CLIENT_ID=your_consumer_key_here
USPS_CLIENT_SECRET=your_consumer_secret_here
NODE_ENV=development

3. Build and Run as stdio

# Development
npm run dev

# Production build
npm run build
npm start

# Run tests
npm test

4. Run as an SSE MCP server


# Production build
npm run start:http

Usage

As a stdio MCP Server

The server runs as a stdio-based MCP server. Configure your AI client to use this server:

{
  "mcpServers": {
    "usps": {
      "command": "node",
      "args": ["/path/to/usps-mcp-server/dist/index.js"],
      "env": {
        "USPS_CLIENT_ID": "your_key",
        "USPS_CLIENT_SECRET": "your_secret"
      }
    }
  }
}

Usage in Claude as stdio

{
  "mcpServers": {
    "usps": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/usps-mcp-server/src/index.ts",
        "--env", "USPS_CLIENT_ID=your_client_id",
        "--env", "USPS_CLIENT_SECRET=your_consumer_secret",
        "--env", "NODE_ENV=prod",
        "--env", "MCP_TRANSPORT=stdio",
        "--env", "USPS_BASE_URL=https://apis.usps.com",
        "--env", "USPS_TEST_BASE_URL=https://apis-tem.usps.com"
      ]
    }
  },
  "globalShortcut": "CommandOrControl+Shift+Space"
}

Usage in VS Code Copilot as SSE

Run the app using SSE

npm run start:http

Configure VS Code mcp.json

{
	"servers": {
		"usps-remote-mcp-server": {
			"url": "http://localhost:3000/mcp",
			"type": "sse"
		}
	},
	"inputs": []
}

Available Tools

validate_address

Validates and standardizes a US address using USPS services.

Parameters:

  • streetAddress (required): Street address (e.g., "123 Main St")
  • city (required): City name (e.g., "New York")
  • state (required): Two-letter state code (e.g., "NY")
  • zipCode (required): ZIP code (e.g., "12345" or "12345-6789")
  • urbanization (optional): Urbanization name (Puerto Rico only)

Example Usage:

{
  "tool": "validate_address",
  "arguments": {
    "streetAddress": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  }
}

Response:

{
  "success": true,
  "originalAddress": {
    "streetAddress": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  },
  "validatedAddress": {
    "address": {
      "streetAddress": "123 MAIN ST",
      "city": "NEW YORK",
      "state": "NY",
      "ZIPCode": "10001",
      "ZIPPlus4": "1234"
    },
    "additionalInfo": {
      "DPVConfirmation": "Y",
      "business": "N"
    }
  },
  "summary": "Standardized address: 123 MAIN ST, NEW YORK, NY, 10001-1234 (delivery point confirmed)"
}

API Integration

USPS Authentication

The server automatically handles OAuth2 authentication:

  1. Uses Client Credentials flow with your USPS Consumer Key/Secret
  2. Caches access tokens and handles automatic refresh
  3. Adds Bearer token to all API requests

Rate Limiting

  • USPS APIs have rate limits (default: 60 calls per hour)
  • The server implements delays between batch requests
  • Consider implementing additional rate limiting for production use

Testing Environment

For development, set NODE_ENV=development to use the USPS Testing Environment for Mailers (TEM):

  • Production: apis.usps.com
  • Testing: apis-tem.usps.com

Error Handling

The server provides comprehensive error handling:

  • Authentication Errors: Invalid credentials, expired tokens
  • Validation Errors: Invalid input parameters, malformed addresses
  • API Errors: USPS service errors, network timeouts
  • Rate Limit Errors: Automatic retry with exponential backoff

Development

Project Structure

src/
├── auth/
│   └── oauth-client.ts      # OAuth2 client implementation
├── services/
│   └── address-validation.ts # Address validation service
├── tools/
│   └── validate-address-tool.ts # MCP tool definition
├── types/
│   └── address-types.ts     # TypeScript type definitions
├── server.ts                # Main MCP server
└── index.ts                 # Entry point

Adding New Tools

  1. Create service class in src/services/
  2. Define tool schema in src/tools/
  3. Register tool in src/server.ts
  4. Add tests and update documentation

License

MIT License - see LICENSE file for details

Support

For USPS API issues:

For MCP Server issues: