Ziptax MCP Server

HTTP-сервер Model Context Protocol (MCP), который предоставляет AI-агентам актуальные ставки налога с продаж и налога на использование в США и Канаде через Ziptax API.

После подключения агент сможет:

Узнавать ставки налога с продаж и налога на использование по адресу, широте и долготе или почтовому индексу.
Получать разбивку ставок по юрисдикциям: штатам, округам, городам и налоговым округам.
Проверять использование аккаунта и доступную квоту.

Официальная документация: docs.zip.tax: MCP Server

Параметры подключения


Конечная точка	`https://mcp.zip-tax.com/`
Метод	`POST`
Транспорт	Streamable HTTP (в большинстве клиентов обозначается как `HTTP`)
Сеансы	Без сохранения состояния
Имя сервера	`ZipTax Sales Tax API`
Внешний API	Ziptax API `v60`

Аутентификация

Передавайте ключ Ziptax API в HTTP-заголовке. Поддерживаются два способа передачи заголовка:

X-API-KEY: your-api-key

Authorization: Bearer your-api-key

Рекомендуется использовать X-API-KEY. Если переданы оба заголовка, приоритет имеет X-API-KEY.
Схема Bearer не зависит от регистра.
Не передавайте ключи API в URL: они могут попасть в журналы.

Получите ключ API на сайте platform.zip.tax.

Настройка клиента

Замените 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 и добавьте сервер:

Name: Ziptax MCP Server
Type: HTTP
URL: https://mcp.zip-tax.com/
Headers: X-API-KEY: your_api_key

Devin

Добавьте интеграцию Ziptax из MCP Marketplace или настройте её в разделе 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"
      }
    }
  }
}

Сохраните ключ в Secrets Manager Devin как секрет с именем ZIPTAX_API_KEY.

Любой другой MCP-клиент

Подключиться можно из любого клиента, поддерживающего транспорт Streamable HTTP:

Type: HTTP
URL: https://mcp.zip-tax.com/
Headers: X-API-KEY: your_api_key

Примеры запросов

«Какова ставка налога с продаж для ZIP-кода 90210?»
«Какова суммарная ставка налога с продаж по адресу 200 Spectrum Center Dr, Irvine, CA?»
«Какова ставка налога с продаж для канадского почтового индекса M5V 2T6 в Toronto, Ontario?»
«Какова была ставка налога с продаж в Nashville, TN (37203) в январе этого года?»
«Сколько запросов к API осталось в моём тарифном плане Ziptax на этот месяц?»

Инструменты

Сервер предоставляет два инструмента только для чтения.

Аннотация	`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 — наименее точный вариант указания местоположения; подробности приведены ниже.

Параметры

Все параметры необязательны, но необходимо указать местоположение одним из способов, перечисленных выше. Согласно схеме, каждый параметр имеет тип string. Для lat, lng, historical и sat_item_total также допускаются JSON-числа. Остальные параметры должны передаваться только в виде строк. Например, передавайте postalcode как "02134", поскольку числовой тип удалит начальный ноль.

Параметр	Описание
`address`	Полный адрес для геокодированного поиска с точностью до конкретного здания. Предпочтительный способ передачи данных.
`lat`	Широта для поиска по координатам. Точность такая же, как у адреса. Используйте вместе с `lng`.
`lng`	Долгота для поиска по координатам. Точность такая же, как у адреса. Используйте вместе с `lat`.
`postalcode`	Пятизначный ZIP-код США или почтовый индекс Канады. Наименее точный вариант: возвращает все ставки, действующие в пределах ZIP-кода, а не одну подтверждённую ставку; поправка на неинкорпорированные территории не применяется. Используйте только в том случае, если адрес и координаты `lat`/`lng` недоступны.
`state`	Двухбуквенный код штата США или провинции Канады (например, `CA`, `ON`).
`city`	Название города.
`county`	Название округа.
`country_code`	`US` (по умолчанию) или `CA` для Канады. Для `CA` требуется тарифный план Pro или Enterprise.
`historical`	Исторический период в формате `YYYYMM` (например, `202601` для января 2026 года). Данные доступны не более чем за последние 12 месяцев. Требуется тарифный план Pro или Enterprise.
`adjustment`	Укажите `auto`, чтобы включить корректировки для неинкорпорированных территорий, предусмотренные для отдельных штатов.
`taxability_code`	Код налогообложения продукта (TIC) для применения правил, зависящих от продукта. Требуется тарифный план Pro или Enterprise. См. раздел Как найти TIC.
`sat_item_total`	Сумма товара для расчёта налога Tennessee Single Article Tax.
`format`	Формат ответа: `json` (по умолчанию) или `xml`.

Пример вызова

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

Ответ

Инструмент возвращает ответ Ziptax API v60 в виде форматированного JSON-текста или, если для format указано значение xml, в исходном формате 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 support@zip.tax 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.
`must be a string` или `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` : `	Ziptax API вернул HTTP-статус, отличный от 200.
`ZipTax API error: API request failed:`	Не удалось подключиться к 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`	Базовый URL API Ziptax

Инфраструктура

Шаблон cloudformation.yaml разворачивает всю необходимую инфраструктуру AWS:

Репозиторий ECR для образов контейнеров
Кластер и сервис ECS Fargate
Балансировщик нагрузки приложений с HTTPS
Сертификат ACM для mcp.zip-tax.com
Размещённая зона Route53 и запись DNS
Группы безопасности и роли IAM

Развёртывание

CI/CD настроен с помощью GitHub Actions:

test.yml — запускается при создании PR и отправке изменений: выполняет проверку кода (golangci-lint) и тесты (go test)
build.yml — запускается в ветке main: собирает образ Docker и отправляет его в ECR
deploy.yml — запускается после сборки: обновляет сервис ECS, используя новый образ
pages.yml — запускается в ветке main при изменении этого README, LICENSE или workflow, а также вручную: публикует README в качестве сайта документации по адресу mcp.zip.tax

build.yml и deploy.yml проходят аутентификацию в AWS, принимая роль IAM через GitHub OIDC; ни один workflow не использует статические ключи AWS. Роль определена в ziptax-terraform (github_oidc.tf) и доверяет только ветке main этого репозитория. ARN роли хранится в переменной репозитория AWS_DEPLOY_ROLE_ARN.

Первоначальная настройка

Разверните стек 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

Добавьте записи NS из размещённой зоны mcp.zip-tax.com в родительскую зону zip-tax.com.
Дождитесь завершения проверки сертификата ACM через DNS.

Лицензия

MIT