# sthan-io/mcp-server [Health: Active]

**Category:** 🗺️ Location Services  
**Repository:** https://github.com/sthan-io/mcp-server  
**GitHub Stars:** 0  
**npm Downloads (last month):** 215  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sthan-io-mcp-server

## Description
US address verification, parsing, autocomplete, forward/reverse geocoding, and IP geolocation via sthan.io APIs. 8 tools, free tier available. npx @sthan/mcp-server

## Tools
Capabilities this server exposes over MCP:

- **sthan_verify_address** — Verify a US address is real and deliverable. Returns standardized format, ZIP+4, DPV, residential/commercial.
- **sthan_parse_address** — Parse freeform US address text into structured components (street number, name, type, direction, unit, city, state, zip).
- **sthan_autocomplete_address** — Suggest complete US addresses from partial input. Sub-100ms.
- **sthan_autocomplete_city** — Suggest US cities from partial input, with state code.
- **sthan_autocomplete_zipcode** — Suggest US ZIP codes from partial input.
- **sthan_geocode** — US address → latitude/longitude with accuracy + confidence.
- **sthan_reverse_geocode** — Latitude/longitude → nearest US street address with distance in meters.
- **sthan_ip_geolocation** — IPv4 or IPv6 → country, region, city, coordinates, timezone, postal code.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server": {
    "command": "npx",
    "args": ["-y","@sthan/mcp-server"],
    "env": {
      "STHAN_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `STHAN_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/sthan-io-mcp-server/readme_