customs-mcp-server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
customs-mcp-server
Customs operations as MCP tools — drop into any AI agent.
14 production-grade customs / trade capabilities (declarations, ship info, tariff, dual-use screening, AI-powered declaration generation, ...) exposed as standard Model Context Protocol tools for Claude Desktop, Claude Code, Cursor, Windsurf, Trae and any other MCP-compatible AI client.
✨ Features
14 MCP tools — every customs-skill capability exposed as a typed tool with zod-validated input
Universal client support — Claude Desktop / Claude Code / Cursor / Windsurf / Trae / Codex / any MCP client
Production auth —
/session/exchange→ 5-minagentToken→ action-code whitelist → tenant isolationPer-call identity override — server-level env default + optional
_identityfield per tool call (multi-user / multi-tenant friendly)AI document maker — multipart upload, no-wait mode,
decIdpolling patternError translation — backend
NEED_BIND/NEED_TENANT/ etc. rendered as actionable English guidanceTiered timeouts — 15 s reads / 180 s upload / 660 s dual-use AI query
Zero runtime deps —
@modelcontextprotocol/sdk+zod+dotenvonly; Node 18+ built-infetch+FormDataDual transport — stdio (Claude Desktop) and Streamable HTTP (remote / self-hosted)
Related MCP server: Bankr Industrial Customs MCP
🚀 Quick Start
1. Set up the backend identity binding
Ask your customs system admin to insert one row into agent_identity_binding
mapping your chosen (platform, externalUserId) to an existing sys_user_id.
Full SQL in docs/identity-binding.md.
2. Configure your AI client
Pick a ready-made config from examples/:
Or use the generic snippet:
{
"mcpServers": {
"customs": {
"command": "npx",
"args": ["-y", "@dearmrzhang/customs-mcp-server", "--transport", "stdio"],
"env": {
"CUSTOMS_API_BASE_URL": "http://your-backend-host:port",
"CUSTOMS_ACCESS_KEY": "your-access-key",
"CUSTOMS_SECRET_KEY": "your-secret-key",
"CUSTOMS_DEFAULT_PLATFORM": "mcp",
"CUSTOMS_DEFAULT_EXTERNAL_USER_ID": "your-bound-username",
"CUSTOMS_DEFAULT_EXTERNAL_CORP_ID": "mcp-prod"
}
}
}
}3. Restart your client and ask
"Use
customs_query_tariffto look up HS code 8471300000."
That's it. The AI agent picks the tool, the MCP server signs the request, exchanges a grant, and returns structured tariff data.
🏗 Architecture
┌────────────────────────────────┐
│ AI client (Claude / Cursor / │
│ Windsurf / Trae / ...) │
└───────────────┬────────────────┘
│ MCP protocol (stdio | HTTP)
┌───────────────▼────────────────┐
│ customs-mcp-server │
│ │
│ • 14 tool handlers │
│ • Identity resolver │
│ • Signer + GrantBroker │
│ (5-min agentToken cache) │
│ • Error translator │
└───────────────┬────────────────┘
│ HTTPS + signed headers
┌───────────────▼────────────────┐
│ Customs backend │
│ /open-api/agent/v1/... │
└─────────────────────────────────┘📚 Documentation
Document | What's inside |
All version changes, including v0.1.2 → v1.0.0 breaking changes, v1.1.0 declaration-list enhancements | |
Complete schema and usage for all 14 tools | |
Backend SQL setup, multi-tenant patterns, troubleshooting | |
Ready-to-paste config snippets for 5 AI clients |
🛠 Environment Variables
Variable | Required | Default | Description |
| ✅ | — | Customs backend root URL |
| ✅ | — | Static signature access key |
| ✅ | — | Static signature secret key |
| ✅ | — | Identity platform (e.g. |
| ✅ | — | Bound external user identifier |
| ✅ | — | Bound external corp identifier |
|
| API path prefix | |
|
| Default request timeout (ms) | |
|
| AI-maker upload timeout (ms) | |
|
| Dual-use slow query timeout (ms) | |
|
| Timestamp tz (must match backend) | |
|
| Channel field for | |
|
| HTTP transport bind host | |
|
| HTTP transport port | |
|
| HTTP transport endpoint | |
|
| Set |
🧪 Available Tools
14 tools across 7 domains. Full schema and examples in tool-reference.md.
Domain | Tools |
Declaration |
|
Ship |
|
Manifest |
|
Tariff |
|
Compliance |
|
Orders |
|
AI Maker |
|
⚠️ Upgrading from v0.1.x
v1.0.0 is a breaking release with mandatory new env vars. See CHANGELOG.md → 1.0.0 for the full list. TL;DR:
Add three identity env vars (
CUSTOMS_DEFAULT_PLATFORM/CUSTOMS_DEFAULT_EXTERNAL_USER_ID/CUSTOMS_DEFAULT_EXTERNAL_CORP_ID)Have your admin insert the matching
agent_identity_bindingrowRename
customs_query_tariff_info→customs_query_tariffSwitch
customs_get_declaration_detailcallers fromcusCiqNotoentryId(ordecIdwhen known)
🛡 Security
CUSTOMS_SECRET_KEYand cachedagentTokens never leave server memoryPer-call
_identityoverrides should not embed PII — they appear in MCP structured responsesAll write tools route through action-code whitelist on the backend
Cross-tenant
ai-makerstatus access is blocked at the backend layer
🤝 Contributing
Issues and PRs welcome at github.com/yak33/customs-mcp-server.
git clone https://github.com/yak33/customs-mcp-server.git
cd customs-mcp-server
pnpm install
pnpm build
pnpm dev:stdio # or dev:http📄 License
🙏 Related Projects
customs-skill — the same 13 customs capabilities as an OpenClaw skill for Feishu/Lark integration
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
100+ MCP tools for AI agents: content metadata, trade intelligence, business-expertise analysis.
Classify, validate & verify HS codes and access tariff compliance data for cross-border trade
TradeStats serves official customs trade statistics (Japan: Ministry of Finance; UK: HMRC) as an MCP server and a web API, built for AI agents. Monthly imports and exports by HS code and partner country, with unit prices, year-on-year changes, price/volume decomposition, supplier concentration, seasonality, mirror trade checks and US-dollar conversion. Search products in English or Japanese. No account needed; a free API key is optional.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI agent toolset for cross-border e-commerce and foreign trade, enabling customer discovery, communication, data analysis, and supplier search via MCP protocol.4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform international trade operations such as calculating landed costs, classifying goods, explaining trade terms, estimating shipping, and converting currencies for Kazakhstan/EAEU/Central Asia trade routes.18 npmMIT
- AlicenseAqualityFmaintenanceProvides 14 MCP tools for AI agent infrastructure, enabling knowledge base queries, skill search, handoffs, blueprint validation, trust scoring, identity verification, SLA validation, and compliance checks.2227 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search Chinese HS commodity codes, retrieve detailed tariff and regulatory information, and calculate import taxes using 2026 import/export tariff data.MIT