USPS Address Validation And Standardization 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:

• USPS Developer Portal Support
• USPS API Documentation
• Getting Started with USPS APIs

For MCP Server issues:

• Create an issue in this repository
• Check the MCP Specification