Customs Mcp Server

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.

[](https://www.npmjs.com/package/@dearmrzhang/customs-mcp-server) [](https://nodejs.org/) [](LICENSE) [](tsconfig.json) [](https://modelcontextprotocol.io/) [](https://github.com/yak33/customs-mcp-server)

English · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)

---

✨ 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)

🚀 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](docs/identity-binding.md).

2. Configure your AI client

Pick a ready-made config from [examples/](examples/):

• [Claude Desktop](examples/claude-desktop.json)
• [Cursor](examples/cursor.json)
• [Windsurf](examples/windsurf.json)
• [Trae](examples/trae.json)
• [Claude Code](examples/claude-code.md)

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

| Document | What's inside | |---|---| | [CHANGELOG.md](CHANGELOG.md) | All version changes, including v0.1.2 → v1.0.0 breaking changes, v1.1.0 declaration-list enhancements | | [docs/tool-reference.md](docs/tool-reference.md) | Complete schema and usage for all 14 tools | | [docs/identity-binding.md](docs/identity-binding.md) | Backend SQL setup, multi-tenant patterns, troubleshooting | | [examples/](examples/) | Ready-to-paste config snippets for 5 AI clients |

🛠 Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | CUSTOMS_API_BASE_URL | ✅ | — | Customs backend root URL | | CUSTOMS_ACCESS_KEY | ✅ | — | Static signature access key | | CUSTOMS_SECRET_KEY | ✅ | — | Static signature secret key | | CUSTOMS_DEFAULT_PLATFORM | ✅ | — | Identity platform (e.g. mcp / cursor) | | CUSTOMS_DEFAULT_EXTERNAL_USER_ID | ✅ | — | Bound external user identifier | | CUSTOMS_DEFAULT_EXTERNAL_CORP_ID | ✅ | — | Bound external corp identifier | | CUSTOMS_API_PREFIX | | /open-api/agent | API path prefix | | CUSTOMS_TIMEOUT_MS | | 15000 | Default request timeout (ms) | | CUSTOMS_UPLOAD_TIMEOUT_MS | | 180000 | AI-maker upload timeout (ms) | | CUSTOMS_DUAL_USE_TIMEOUT_MS | | 660000 | Dual-use slow query timeout (ms) | | CUSTOMS_TIMESTAMP_TIMEZONE | | Asia/Shanghai | Timestamp tz (must match backend) | | CUSTOMS_DEFAULT_CHANNEL | | ${PLATFORM} | Channel field for /session/exchange | | MCP_HTTP_HOST | | 0.0.0.0 | HTTP transport bind host | | MCP_HTTP_PORT | | 8787 | HTTP transport port | | MCP_HTTP_PATH | | /mcp | HTTP transport endpoint | | CUSTOMS_DEBUG | | 0 | Set 1 for verbose stderr debug logs |

🧪 Available Tools

14 tools across 7 domains. Full schema and examples in [tool-reference.md](docs/tool-reference.md).

| Domain | Tools | |---|---| | Declaration | customs_get_declaration_status · customs_query_declaration_list · customs_get_declaration_detail · customs_get_import_export_status · customs_get_full_process_tracking | | Ship | customs_query_ship_info (with auto I→E fallback) · customs_query_ship_plan | | Manifest | customs_query_manifest_info · customs_query_ship_manifest_info | | Tariff | customs_query_tariff | | Compliance | customs_query_dual_use_item (slow AI query) | | Orders | customs_create_order_draft (pre-check only) | | AI Maker | customs_submit_ai_maker · customs_get_ai_maker_status |

⚠️ Upgrading from v0.1.x

v1.0.0 is a breaking release with mandatory new env vars. See [CHANGELOG.md → 1.0.0](CHANGELOG.md#100--2026-05-24) 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)

1. Have your admin insert the matching agent_identity_binding row
2. Rename customs_query_tariff_info → customs_query_tariff
3. 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](LICENSE).

🙏 Related Projects

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

---

Built with 🦞 by ZHANGCHAO · v1.1.0 · 2026-05-27

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yak33
• Source: yak33/customs-mcp-server
• License: MIT
• Homepage: https://www.npmjs.com/package/@dearmrzhang/customs-mcp-server

Install and usage instructions live in the source repository linked above.