sthan-io

Sthan MCP サーバー

sthan.io 向けの MCP サーバー — AI アシスタントで、米国の住所の検証、解析、入力補完、ジオコーディング、および IP ジオロケーションの検索ができます。Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、および MCP 互換のあらゆるクライアントで動作します。

8 個のツール · TypeScript · stdio トランスポート · 無料プランあり、クレジットカード不要。

---

選ばれる理由

• 実際の米国郵便データ — 住所を推測ではなく、信頼できる郵便記録と照合して検証します。配達地点検証（DPV）、ZIP+4、居住用／商業用の区分を返します。
• 100 ミリ秒未満の入力補完 — 住所、市区町村、ZIP コードの候補を高速に表示します。
• 高精度なジオコーディング — フォワードジオコーディングでは、精度分類（屋上／補間／重心／概算）と信頼度スコアを返すため、AI が結果の信頼性を判断できます。
• IPv4 + IPv6 のジオロケーション — 国、地域、市区町村、座標、郵便番号、現在の現地時刻を含むタイムゾーン、国旗、通貨、国際電話番号、ネットワーク（ASN、ISP、組織）、モバイル／プロキシ／ホスティングのフラグ、逆引き DNS、信頼度スコアを取得できます。
• クレジットカード不要の無料プラン — sthan.io/dashboard で 1 分以内にキーを取得できます。

ツール

ツール	機能
sthan_verify_address	米国の住所が実在し、配達可能かを検証します。標準化された形式、ZIP+4、DPV、居住用／商業用の区分を返します。
sthan_parse_address	自由形式の米国住所テキストを、構造化された構成要素（番地、通りの名前、種類、方向、部屋番号、市区町村、州、ZIP コード）に解析します。
sthan_autocomplete_address	入力途中のテキストから米国の完全な住所候補を提示します。100 ミリ秒未満で応答します。
sthan_autocomplete_city	入力途中のテキストから、州コード付きで米国の市区町村候補を提示します。
sthan_autocomplete_zipcode	入力途中のテキストから米国の ZIP コード候補を提示します。
sthan_geocode	米国の住所 → 緯度／経度（精度と信頼度付き）、郡、ZIP+4、タイムゾーンを返します。
sthan_reverse_geocode	緯度／経度 → 最寄りの米国の住所を、距離（メートル）、郡、ZIP+4、タイムゾーンとともに返します。limit（最大 10）を指定すると、近隣の住所も一覧表示します。
sthan_ip_geolocation	IPv4 または IPv6 → 位置情報（国から郵便番号まで、現地時刻、国旗、通貨）、その IP のネットワーク情報（ASN、ISP、プロキシ／ホスティングのフラグ）、信頼度スコアを返します。

クイックスタート

1. 無料の API キーを取得する

sthan.io に登録し、ダッシュボードからキーを作成します。クレジットカードは不要です。

2. ワンクリックインストール

• Claude Desktop：sthan.mcpb をダウンロードして、ダブルクリックしてください。Claude が API キーを尋ね、システムのキーチェーンに保存します。ほかにインストールするものはありません。
• VS Code：ボタンをクリックしてください。VS Code が API キーを尋ね、安全に保存します。
• Cursor：ボタンをクリックし、Cursor Settings > MCP で your_key_here を自分のキーに置き換えてください。
• Claude Code：claude mcp add sthan -e STHAN_API_KEY=your_key_here -- npx -y @sthan/mcp-server（詳細は以下を参照）。

3. または手動でセットアップする

your_key_here をご自身のキーに置き換えてください。以下のセットアップでは、いずれも npm から最新の @sthan/mcp-server をダウンロードし、https://api.sthan.io のライブ API を呼び出します。

Claude Code（ターミナル）：

claude mcp add sthan -e STHAN_API_KEY=your_key_here -- npx -y @sthan/mcp-server

Windows ネイティブ環境では、npx を cmd /c でラップしてください。

claude mcp add sthan -e STHAN_API_KEY=your_key_here -- cmd /c npx -y @sthan/mcp-server

すべてのプロジェクトで使うには、--scope user を追加してください。claude を起動し、/mcp と入力して sthan が接続されていることを確認してください。

Claude Desktop：claude_desktop_config.json（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）を編集し、Claude Desktop を再起動してください。

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

Cursor：同じ JSON を ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1つのプロジェクト）に記述します。

Windsurf：同じ JSON を ~/.codeium/windsurf/mcp_config.json に記述します。

VS Code：.vscode/mcp.json を作成します。VS Code でキーの入力を求められるのは一度だけで、安全に保存されます。

{
  "inputs": [
    { "type": "promptString", "id": "sthan-api-key", "description": "sthan.io API key", "password": true }
  ],
  "servers": {
    "sthan": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sthan/mcp-server"],
      "env": { "STHAN_API_KEY": "${input:sthan-api-key}" }
    }
  }
}

AI クライアントなしで試す（ブラウザーで公式 MCP Inspector を開きます）：

npx @modelcontextprotocol/inspector -e STHAN_API_KEY=your_key_here npx -y @sthan/mcp-server

Connect をクリックし、Tools > List Tools の順に選択して、ツールを選んで実行します。

トラブルシューティング

• npx -y の -y は省略しないでください。省略すると、npx は「OK to install?」への回答を待ち続けますが、AI クライアントからは回答できないため、サーバーが起動しません。
• Windows では、PowerShell またはコマンドプロンプトから claude mcp add ... cmd /c ... コマンドを実行してください。Git Bash は /c を C:/ に書き換えるため、タイムアウトする不正なコマンドが保存されます（修正方法：先頭に MSYS_NO_PATHCONV=1 を付けます）。
• Windows でクライアントに spawn npx ENOENT と表示された場合は、"command": "cmd" と "args": ["/c", "npx", "-y", "@sthan/mcp-server"] を使用してください。
• ライブの郵便番号検索が必要な場合、住所の検証と解析には最大で約2分かかることがあります。クライアントがそれより早く処理を打ち切る場合は、ツールのタイムアウトを延長してください（Claude Code：claude の起動前に MCP_TOOL_TIMEOUT=150000 を設定します。MCP Inspector：Configuration パネルで Request Timeout を延長します）。

プロンプトの例

設定が完了したら、AI アシスタントに自然な言葉で尋ねるだけです。

• 「123 Main St, New York, NY 10001 は実在し、配達可能な住所ですか？」
• 「この住所を解析してください：apt 2b 500 broadway new york ny」
• 「1600 Pennsylvania Ave, Washington DC の座標は何ですか？」
• 「40.7128, -74.0060 に最も近い住所はどこですか？」
• 「IP アドレス 8.8.8.8 の場所はどこですか？」
• 「『San Fr』で始まる米国の都市を提案してください。」

環境変数

変数	必須	説明
STHAN_API_KEY	はい	sthan.io API キー（開発環境では sthan_test_*、本番環境では sthan_live_*）
STHAN_API_URL	いいえ	ベース URL の上書き（デフォルト：https://api.sthan.io）

応答時間

ほとんどの呼び出しは1～3秒で応答します。住所が sthan.io 独自のデータで照合できず、ライブの郵便番号検索が必要な場合、住所の検証と解析には最大で約2分かかることがあります。そのため、サーバーはこの2つのツールについて最大150秒間応答を待ちます。MCP クライアントがそれより早く待機を終了する場合は、ツールのタイムアウトを延長してください（たとえば、Claude Code では MCP_TOOL_TIMEOUT=150000 を設定します）。

パッケージ

このモノレポでは、2つのパッケージを公開しています。

パッケージ	npm	用途
@sthan/mcp-server		MCP サーバー本体 — クライアントが起動するバイナリ
@sthan/core		sthan.io API をプログラムから直接利用するための TypeScript SDK

開発

git clone https://github.com/sthan-io/mcp-server.git
cd mcp-server
npm install
npm run build --workspaces

次に、STHAN_API_KEY=sthan_test_... node packages/mcp-server/dist/index.js でサーバーを実行します。

リンク

• ホームページ： https://sthan.io
• API ドキュメント： https://sthan.io/docs
• OpenAPI 仕様： https://api.sthan.io/openapi.json
• AI 向けリファレンス（llms-full.txt）： https://api.sthan.io/llms-full.txt
• 料金： https://sthan.io/pricing/united-states
• サポート： https://sthan.io/support
• Glama： https://glama.ai/mcp/servers/sthan-io/mcp-server

ライセンス

MIT — LICENSE を参照してください。