Ziptax Sales Tax API

Ziptax MCP Server

AI エージェントに Ziptax API から米国およびカナダの売上税・使用税率をリアルタイムで提供する、HTTP Model Context Protocol（MCP） サーバーです。

接続すると、エージェントは次のことができます。

• 住所、緯度・経度、または郵便番号から売上税・使用税率を調べる。
• 管轄区域ごとの内訳（州、郡、市、地区）を取得する。
• アカウントの使用状況とクォータを確認する。

公式ドキュメント：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 キーを送信します。次の 2 種類のヘッダー方式に対応しています。

X-API-KEY: your-api-key

Authorization: Bearer your-api-key

• X-API-KEY を推奨します。両方のヘッダーが存在する場合は、X-API-KEY が優先されます。
• Bearer スキームでは大文字と小文字が区別されません。
• API キーを URL に含めないでください。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, Irvine, CA の合計売上税率はいくらですか？」
• 「カナダ、オンタリオ州トロントの郵便番号 M5V 2T6 の売上税率はいくらですか？」
• 「今年の 1 月、TN 州ナッシュビル（37203）の売上税率はいくらでしたか？」
• 「今月、Ziptax プランで API リクエストをあと何回利用できますか？」

ツール

サーバーは読み取り専用ツールを 2 つ公開します。

注釈	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 コードと重なるすべての税率を返します。住所または lat/lng を利用できない場合にのみ使用してください。
state	米国の州またはカナダの州・準州を表す 2 文字のコードです（例：CA、ON）。
city	市区町村名です。
county	郡名です。
country_code	US（デフォルト）またはカナダの場合は CA です。CA の利用には Pro または Enterprise プランが必要です。
historical	YYYYMM 形式の過去の期間です（例：2026 年 1 月の場合は 202601）。過去 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"
  }
}

レスポンス

このツールは、Ziptax API v60 のレスポンスを整形済み JSON テキストで返します。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": {}
}

レスポンス

このツールは、Ziptax API v60 のアカウントメトリクスのレスポンスを整形済み JSON テキストで返します。

{
  "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	プランまたは上限の変更方法です。

詳細については、アカウントメトリクスをご覧ください。

エラー処理

エラーは JSON-RPC エラーではなく、isError: true とテキストメッセージを含むツールの結果として返されます。

メッセージ	原因
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