Ziptax Sales Tax API

Ziptax MCP 服务

一个 HTTP Model Context Protocol (MCP) 服务，通过 Ziptax API 为 AI Agent 提供实时的美国和加拿大销售税与使用税税率。

连接后，Agent 可以：

• 按街道地址、纬度/经度或邮政编码查询销售税与使用税税率。
• 获取司法辖区级别的细分信息（州、县、市和地区）。
• 查看账户用量和配额。

官方文档：docs.zip.tax：MCP Server

连接详情

端点	https://mcp.zip-tax.com/
方法	POST
传输方式	Streamable HTTP（大多数客户端称为 HTTP）
会话	无状态
服务名称	ZipTax Sales Tax API
上游 API	Ziptax API v60

身份验证

通过 HTTP 标头发送 Ziptax API 密钥。支持两种标头方式：

X-API-KEY: your-api-key

Authorization: Bearer your-api-key

• 推荐使用 X-API-KEY。如果两个标头都存在，则优先使用 X-API-KEY。
• Bearer 方案不区分大小写。
• 请勿在 URL 中传递 API 密钥。URL 中的密钥可能会出现在日志里。

请前往 platform.zip.tax 获取 API 密钥。

客户端配置

将 your_api_key 替换为你的 Ziptax API 密钥。

Claude Code

claude mcp add --transport http ziptax https://mcp.zip-tax.com/ --header "X-API-KEY: your_api_key"

Claude Desktop

将此代码块添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "ziptax": {
      "type": "http",
      "url": "https://mcp.zip-tax.com/",
      "headers": {
        "X-API-KEY": "your_api_key"
      }
    }
  }
}

Cursor

前往 Settings → MCP 并添加服务：

• 名称： Ziptax MCP Server
• 类型： HTTP
• URL： https://mcp.zip-tax.com/
• 标头： X-API-KEY: your_api_key

Devin

从 MCP Marketplace 添加 Ziptax 集成，或在 Settings → MCP Marketplace → Add Your Own 中进行配置：

{
  "mcpServers": {
    "ziptax-sales-tax-api": {
      "transport": "shttp",
      "url": "https://mcp.zip-tax.com/",
      "headers": {
        "X-API-KEY": "$ZIPTAX_API_KEY"
      }
    }
  }
}

在 Devin 的 Secrets Manager 中将密钥保存为名为 ZIPTAX_API_KEY 的机密。

其他 MCP 客户端

任何支持 Streamable HTTP 传输方式的客户端都可以连接：

• 类型： HTTP
• URL： https://mcp.zip-tax.com/
• 标头： X-API-KEY: your_api_key

示例提示词

• “90210 邮政编码的销售税税率是多少？”
• “加利福尼亚州尔湾市 200 Spectrum Center Dr 的合并销售税税率是多少？”
• “加拿大安大略省多伦多市邮政编码 M5V 2T6 的销售税税率是多少？”
• “今年 1 月田纳西州纳什维尔（37203）的销售税税率是多少？”
• “这个月我的 Ziptax 套餐还剩多少次 API 请求？”

工具

该服务提供两个只读工具。

注解	lookup_tax_rate	get_account_metrics
title	查询销售税税率	获取账户用量指标
readOnlyHint	true	true
destructiveHint	false	false
idempotentHint	true	true
openWorldHint	false	false

lookup_tax_rate

查询美国或加拿大某个地点的销售税与使用税税率。返回按司法辖区（州、县、市、地区）细分的税率。

地点要求

请提供以下其中一项：

• address：完整的街道地址，可精确到具体门牌。这是首选输入。
• lat 和 lng：一个地理坐标点，精度与地址相同，可精确到具体门牌。

输入架构通过 anyOf 约束声明了这一要求。postalcode 是精度最低的地点输入；详情请见下文说明。

参数

所有参数均为可选项，但须满足上述位置要求；架构将每个参数都声明为字符串。lat、lng、historical 和 sat_item_total 也接受 JSON 数字。其他所有参数都必须是字符串。例如，postalcode 应以 "02134" 的形式发送，因为数字会丢失开头的零。

参数	描述
address	完整街道地址，用于门牌级地理编码查询。首选输入。
lat	用于基于坐标查询的纬度。精度与地址相同，均为门牌级。与 lng 配合使用。
lng	用于基于坐标查询的经度。精度与地址相同，均为门牌级。与 lat 配合使用。
postalcode	美国 ZIP 邮政编码（5 位）或加拿大邮政编码。精度最低的选项：返回与 ZIP 区域重叠的所有税率，而非单一权威税率，且不会针对未建制地区进行调整。仅在没有地址或经纬度时使用。
state	两位字母的美国州或加拿大省代码（例如 CA、ON）。
city	城市名称。
county	县名称。
country_code	US（默认值）或表示加拿大的 CA。CA 需要 Pro 或 Enterprise 计划。
historical	YYYYMM 格式的历史时段（例如 202601 表示 2026 年 1 月）。查询范围仅限过去 12 个月。需要 Pro 或 Enterprise 计划。
adjustment	设置为 auto，以启用州特定的未建制地区调整。
taxability_code	用于产品特定税务规则的产品应税性代码（TIC）。需要 Pro 或 Enterprise 计划。请参阅如何查找 TIC。
sat_item_total	用于田纳西州单件商品税计算的商品总额。
format	响应格式：json（默认值）或 xml。

调用示例

{
  "name": "lookup_tax_rate",
  "arguments": {
    "address": "200 Spectrum Center Dr, Irvine, CA 92618"
  }
}

响应

该工具以美化格式的 JSON 文本返回 Ziptax API v60 响应；如果 format 为 xml，则原样返回 API 的 XML 响应。它与按地址查询的 REST API响应一致：

{
  "metadata": {
    "version": "v60",
    "response": {
      "code": 100,
      "name": "RESPONSE_CODE_SUCCESS",
      "message": "Successful API Request.",
      "definition": "http://api.zip-tax.com/request/v60/schema"
    }
  },
  "baseRates": [
    {
      "rate": 0.0725,
      "jurType": "US_STATE_SALES_TAX",
      "jurName": "CA",
      "jurDescription": "US State Sales Tax",
      "jurTaxCode": "06"
    },
    {
      "rate": 0.005,
      "jurType": "US_COUNTY_SALES_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Sales Tax",
      "jurTaxCode": "30"
    }
  ],
  "taxSummaries": [
    {
      "rate": 0.0775,
      "taxType": "SALES_TAX",
      "summaryName": "Total Base Sales Tax",
      "displayRates": [
        { "name": "Total Rate", "rate": 0.0775 }
      ]
    }
  ],
  "addressDetail": {
    "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
    "incorporated": "true",
    "geoLat": 33.65253,
    "geoLng": -117.74794
  }
}

metadata.response.code 表示 API 响应代码。完整列表请参阅响应代码。

get_account_metrics

获取经过身份验证的 Ziptax 账户的使用情况指标和配额信息。不接受参数。

调用示例

{
  "name": "get_account_metrics",
  "arguments": {}
}

响应

该工具以美化格式的 JSON 文本返回 Ziptax API v60 账户指标响应：

{
  "request_count": 4215,
  "request_limit": 100000,
  "usage_percent": 4.215,
  "is_active": true,
  "message": "Contact [email protected] to modify your account"
}

字段	描述
request_count	当前计费周期内使用此密钥发出的请求数。
request_limit	计划包含的请求数。0 表示不限量。
usage_percent	request_count / request_limit * 100。
is_active	如果密钥已停用，则为 false。
message	如何更改计划或限额。

详情请参阅账户指标。

错误处理

错误会作为包含 isError: true 和文本消息的工具结果返回，而不是 JSON-RPC 错误。

消息	原因
Missing API key. Send it in the X-API-KEY header or as a Bearer token in the Authorization header. ...	工具调用未提供 API 密钥标头。
<parameter> must be a string 或 <parameter> must be a string or number	lookup_tax_rate 参数使用了不受支持的类型。
Provide a location: a full street address, or both lat and lng	调用 lookup_tax_rate 时未提供 address、lat/lng 坐标对或 postalcode。
ZipTax API error: API returned status <code>: <body>	Ziptax API 返回了非 200 HTTP 状态码。
ZipTax API error: API request failed: <detail>	无法连接 Ziptax API，或其在 15 秒内未响应。

本地开发

# Run the server
go run .

# Run tests
go test -v ./...

# Build and run the Docker image
docker build -t ziptax-mcp .
docker run -p 8080:8080 ziptax-mcp

服务默认监听端口 8080：

• POST /：MCP 端点
• GET /health：健康检查，返回 {"status":"ok"}

环境变量

变量	默认值	描述
PORT	8080	服务监听端口
ZIPTAX_API_BASE_URL	https://api.zip-tax.com	Ziptax API 基础 URL

基础设施

cloudformation.yaml 模板会配置完整的 AWS 基础设施：

• 用于容器映像的 ECR 存储库
• ECS Fargate 集群和服务
• 启用 HTTPS 的 Application Load Balancer
• mcp.zip-tax.com 的 ACM 证书
• Route53 托管区域和 DNS 记录
• 安全组和 IAM 角色

部署

CI/CD 由 GitHub Actions 处理：

1. test.yml - 在 PR 和推送时运行：代码检查（golangci-lint）和测试（go test）
2. build.yml - 在 main 分支上运行：构建 Docker 映像并推送到 ECR
3. deploy.yml - 在构建后运行：使用新映像更新 ECS 服务
4. pages.yml - 在 main 分支上，当此 README、LICENSE 或工作流发生更改时运行，也可手动触发：将 README 发布为文档站点，网址为 mcp.zip.tax

build.yml 和 deploy.yml 通过 GitHub OIDC 假设 IAM 角色来向 AWS 进行身份验证；没有任何工作流使用静态 AWS 密钥。该角色在 ziptax-terraform（github_oidc.tf）中定义，并且仅信任此仓库的 main 分支。其 ARN 是仓库变量 AWS_DEPLOY_ROLE_ARN。

初始设置

1. 部署 CloudFormation 堆栈：

   aws cloudformation deploy \
     --template-file cloudformation.yaml \
     --stack-name ziptax-mcp \
     --parameter-overrides ImageUri=<ECR_URI>:latest \
     --capabilities CAPABILITY_NAMED_IAM \
     --region us-east-1
   

2. 将 mcp.zip-tax.com 托管区域中的 NS 记录添加到父级 zip-tax.com 区域。

3. 等待 ACM 证书完成 DNS 验证。

许可证

MIT