MCP Server

What sthan-io/mcp-server MCP server does

The sthan-io/mcp-server MCP server connects an MCP-compatible AI client to sthan.io location APIs. Its eight tools cover two related areas: US postal and geographic data, plus IP geolocation.

Address verification checks whether a US address is real and deliverable. The response can include a standardized address, ZIP+4, delivery point validation (DPV), and a residential or commercial classification. Parsing handles freeform US address text and separates fields such as street number, street name, street type, direction, unit, city, state, and ZIP code.

The autocomplete tools return suggestions for partial US addresses, cities, and ZIP codes. Forward geocoding converts a US address into latitude and longitude, with an accuracy classification and confidence score. Reverse geocoding finds the nearest US street address for coordinates and reports the distance in meters. IP geolocation accepts IPv4 or IPv6 and returns country, region, city, coordinates, timezone, and postal code information.

How it works

The server uses the MCP stdio transport. An MCP client launches the npm package locally, and the server calls the sthan.io API using the configured API key. The repository identifies the MCP package as @sthan/mcp-server; its separate @sthan/core package is a TypeScript SDK for direct API use rather than the MCP server itself.

Autocomplete is intended for typeahead-style use and is described as having sub-100ms response times. Geocoding responses include metadata that helps an agent distinguish more precise results, such as rooftop data, from less precise classifications such as approximate results.

Setup and configuration

Install or launch the server with npx -y @sthan/mcp-server in an MCP client configuration. Set STHAN_API_KEY to a key obtained from the sthan.io dashboard. The documentation describes development keys using the sthan_test_* prefix and production keys using sthan_live_*.

STHAN_API_URL is optional and can override the default API base URL, which is https://api.sthan.io. The README provides configurations for Claude Desktop, Claude Code, Cursor, and VS Code, and states that the server works with Windsurf and other MCP-compatible clients.

A local source checkout can also be built with npm workspaces. After building, the repository documents running node packages/mcp-server/dist/index.js with STHAN_API_KEY set.

Tools and capabilities

The sthan-io/mcp-server MCP server exposes these tools:

• sthan_verify_address validates deliverability and returns postal details.
• sthan_parse_address extracts components from freeform US address text.
• sthan_autocomplete_address suggests complete US addresses.
• sthan_autocomplete_city suggests US cities with state codes.
• sthan_autocomplete_zipcode suggests US ZIP codes.
• sthan_geocode converts a US address to coordinates with accuracy and confidence data.
• sthan_reverse_geocode finds a nearby US street address from coordinates.
• sthan_ip_geolocation looks up location data for IPv4 or IPv6 addresses.

Limitations and notes

The documented address operations are specifically for the United States. Running the server requires an sthan.io API key, although the README describes a free tier that does not require a credit card. The server depends on the sthan.io APIs for its address, geocoding, and IP location results, so the optional API URL setting is useful only when a different compatible base URL is needed.

The project is released under the MIT license. The repository describes the package as TypeScript-based and publishes it through npm.