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.

English · 简体中文 · 日本語

✨ 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-min agentToken → action-code whitelist → tenant isolation

• Per-call identity override — server-level env default + optional _identity field per tool call (multi-user / multi-tenant friendly)

• AI document maker — multipart upload, no-wait mode, decId polling pattern

• Error translation — backend NEED_BIND / NEED_TENANT / etc. rendered as actionable English guidance

• Tiered timeouts — 15 s reads / 180 s upload / 660 s dual-use AI query

• Zero runtime deps — @modelcontextprotocol/sdk + zod + dotenv only; Node 18+ built-in fetch + FormData

• Dual transport — stdio (Claude Desktop) and Streamable HTTP (remote / self-hosted)

Related MCP server: ShippingRates

🚀 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/:

• Claude Desktop

• Cursor

• Windsurf

• Trae

• Claude Code

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_tariff to 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

🛠 Environment Variables

🧪 Available Tools

14 tools across 7 domains. Full schema and examples in tool-reference.md.

⚠️ 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:

1. Add three identity env vars (CUSTOMS_DEFAULT_PLATFORM / CUSTOMS_DEFAULT_EXTERNAL_USER_ID / CUSTOMS_DEFAULT_EXTERNAL_CORP_ID)

2. Have your admin insert the matching agent_identity_binding row

3. Rename customs_query_tariff_info → customs_query_tariff

4. Switch customs_get_declaration_detail callers from cusCiqNo to entryId (or decId when known)

🛡 Security

• CUSTOMS_SECRET_KEY and cached agentTokens never leave server memory

• Per-call _identity overrides should not embed PII — they appear in MCP structured responses

• All write tools route through action-code whitelist on the backend

• Cross-tenant ai-maker status 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

MIT © ZHANGCHAO. See LICENSE.

🙏 Related Projects

• customs-skill — the same 13 customs capabilities as an OpenClaw skill for Feishu/Lark integration