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 ms — 地址、城市和 ZIP 建议的响应速度达到即时输入提示级别。
• 强大的地理编码 — 正向地理编码会返回精度分类（屋顶级 / 插值 / 质心 / 近似）和置信度评分，让 AI 知道何时可以信任结果。
• IPv4 + IPv6 地理位置 — 国家、地区、城市、坐标、邮政编码、时区及当前当地时间、旗帜、货币、拨号代码、网络（ASN、ISP、组织）、移动网络/代理/托管标记、反向 DNS 和置信度评分。
• 免费套餐，无需信用卡 — 在 sthan.io/dashboard 不到一分钟即可获取密钥。

工具

工具	功能
sthan_verify_address	验证美国地址是否真实且可投递。返回标准化格式、ZIP+4、DPV、住宅/商业标记。
sthan_parse_address	将自由格式的美国地址文本解析为结构化组成部分（门牌号、街道名称、街道类型、方向、单元号、城市、州、邮编）。
sthan_autocomplete_address	根据部分输入建议完整的美国地址。耗时低于 100 ms。
sthan_autocomplete_city	根据部分输入建议美国城市，并提供州代码。
sthan_autocomplete_zipcode	根据部分输入建议美国 ZIP 邮政编码。
sthan_geocode	美国地址 → 纬度/经度及精度、置信度、县、ZIP+4 和时区。
sthan_reverse_geocode	纬度/经度 → 最近的美国街道地址，并提供距离（米）、县、ZIP+4 和时区；limit（最多 10）还会列出附近地址。
sthan_ip_geolocation	IPv4 或 IPv6 → 地理位置（从国家到邮政编码、当地时间、旗帜、货币）、背后的网络（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，并调用实时 API https://api.sthan.io。

Claude Code（终端）：

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

在原生 Windows 上，使用 cmd /c 包装 npx：

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：在 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）中使用相同的 JSON。

Windsurf：在 ~/.codeium/windsurf/mcp_config.json 中使用相同的 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 会等待“是否安装？”的确认，而 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 分钟），因此服务会为这两个工具等待最长 150 秒。如果 MCP 客户端提前停止等待，请调高工具超时时间（例如，在 Claude Code 中设置 MCP_TOOL_TIMEOUT=150000）。

软件包

这个 monorepo 会发布两个软件包：

软件包	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。