Validates and standardizes US addresses using the official USPS Address Validation API, providing tools for address validation and standardization.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@USPS Address Validation and Standardization MCP Server validate this address: 1600 Amphitheatre Pkwy, Mountain View, CA 94043"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides AI assistants with tools to interact with USPS services, specifically address validation and standardization.
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
Related MCP server: UPS MCP Server
USPS Business Account: You need a USPS Business Account to access the APIs. Read the Getting Started at USPS Developer Portal
API Credentials: Obtain Consumer Key and Consumer Secret from your API app
git clone https://github.com/bailur/usps-mcp-server.git
cd usps-mcp-server
npm installCopy the example environment file and configure your USPS credentials:
cp .env.example .envEdit .env with your USPS API credentials:
USPS_CLIENT_ID=your_consumer_key_here
USPS_CLIENT_SECRET=your_consumer_secret_here
NODE_ENV=development# Development
npm run dev
# Production build
npm run build
npm start
# Run tests
npm test
# Production build
npm run start:http
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"
}
}
}
}{
"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"
}Run the app using SSE
npm run start:httpConfigure VS Code mcp.json
{
"servers": {
"usps-remote-mcp-server": {
"url": "http://localhost:3000/mcp",
"type": "sse"
}
},
"inputs": []
}validate_addressValidates 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)"
}The server automatically handles OAuth2 authentication:
Uses Client Credentials flow with your USPS Consumer Key/Secret
Caches access tokens and handles automatic refresh
Adds Bearer token to all API requests
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
For development, set NODE_ENV=development to use the USPS Testing Environment for Mailers (TEM):
Production: apis.usps.com
Testing: apis-tem.usps.com
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
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 pointCreate service class in src/services/
Define tool schema in src/tools/
Register tool in src/server.ts
Add tests and update documentation
MIT License - see LICENSE file for details
For USPS API issues:
For MCP Server issues:
Create an issue in this repository
Check the MCP Specification
Validate and standardize a US address using USPS Address Validation API. Returns corrected address information, delivery point validation, and address standardization.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City name (e.g., "New York", "Los Angeles") | |
| state | Yes | Two-letter state code (e.g., "NY", "CA", "TX") | |
| zipCode | Yes | ZIP code - 5 digits or ZIP+4 format (e.g., "12345", "12345-6789") | |
| urbanization | No | Urbanization name (Puerto Rico addresses only) | |
| streetAddress | Yes | Street address (e.g., "123 Main St", "456 Oak Avenue Apt 2B") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool calls the USPS API and returns corrected address information, delivery point validation, and standardization. However, it does not disclose potential side effects (e.g., external API dependency, rate limits, authentication requirements) or behavior on invalid addresses. This is partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that effectively front-loads the tool's purpose and return value. Every phrase is informative: the API used, the action performed, and the outcomes. There is zero wasted content, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description adequately explains the return values (corrected address, delivery point validation, standardization) and the underlying service. It lacks explicit details about error handling or edge cases (e.g., invalid addresses), but the tool is relatively straightforward and the schema covers all inputs. The description is complete enough for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and all parameters already have detailed descriptions in the schema. The tool description does not add any additional meaning to the parameters beyond what the schema provides. The baseline score of 3 applies because the schema fully covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('validate and standardize') and identifies the resource ('US address') and the API used ('USPS Address Validation API'). It clearly states what the tool does and distinguishes it from any hypothetical alternatives by specifying the USPS-specific service. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for US address validation and mentions the return of corrected information, but it does not provide explicit guidance on when to use this tool vs alternatives, nor does it state when not to use it (e.g., for international addresses). No sibling tools are listed, so some guidance could be helpful but is not strictly required given the clear scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0validate_addressWith only one tool, there is no possibility of confusion or overlap. The tool's purpose is unambiguous and clearly defined.
The single tool name 'validate_address' follows a clear verb_noun pattern, which is consistent with best practices. There are no other tools to compare, but the naming is clean and predictable.
The server is narrowly scoped to USPS address validation and standardization. One tool adequately covers this specific function without unnecessary bloat, making the count perfectly appropriate for the purpose.
The tool fully addresses the domain of individual address validation by providing validation, standardization, and delivery point information. There are no obvious gaps for the stated purpose of the server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Address validation & geocoding for AI agents: 240+ countries, UK PAF, free US/CA enrichment
Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
US address intelligence: 120M+ addresses, verify, suggest, reverse geocode, coverage stats.
Verify addresses, email addresses, and phone numbers with confidence scores.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bailur/usps-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
