Harukibox

What harukibox MCP server does

The harukibox MCP server exposes a harukibox account to compatible AI agents. Its tools cover the operational data used by a Japan proxy-buying business: products, orders, buyers, and shipments. Agents can retrieve records, search across resources, filter results, paginate lists, and create products when the account has the required write scope.

The package also supports token self-inspection and revoking the caller’s own tokens. Product creation is subject to the account plan’s quota rules. Read operations use scopes such as me, *:read, or search, while product creation and token revocation require *:write.

How it works

The local package is distributed as @harukibox/mcp and communicates with an MCP client over stdio. A client starts it with npx -y @harukibox/mcp; the access token is supplied through the HARUKIBOX_TOKEN environment variable. This arrangement is suitable for desktop clients and locally developed agents that can launch an MCP process.

A remote MCP surface is also available at https://harukibox.com/api/agent/mcp using Streamable HTTP. The underlying harukibox APIs provide OAuth 2.1 flows, including PKCE and device authorization, as well as REST and OpenAPI access for applications that do not use MCP.

The implementation supports the MCP 2026-07-28 revision while retaining compatibility with clients that still use the earlier initialization handshake. The newer protocol is stateless: requests carry protocol information and client metadata, and the server provides capability discovery through server/discover.

Setup and configuration

Install the CLI if you need its login and checking commands:

npm install -g @harukibox/cli
harukibox login

After authentication, the CLI stores the token at ~/.config/harukibox/config.json. Configure an MCP client to launch the package and pass the token, for example:

{
  "mcpServers": {
    "harukibox": {
      "command": "npx",
      "args": ["-y", "@harukibox/mcp"],
      "env": { "HARUKIBOX_TOKEN": "hrk_live_..." }
    }
  }
}

Run harukibox mcp check to check a deployment against the stated protocol specification.

Tools and capabilities

The harukibox MCP server provides eight tools covering:

• Product listing with search, status filters, and pagination
• Product lookup by ID
• Order listing by status or buyer
• Buyer lookup by name, phone, or email
• Shipment listing
• Search across supported resources
• Token self-introspection
• Product creation and self-token revocation, subject to write scopes

The repository also includes examples for Claude Desktop, Python agents, n8n workflows, ChatGPT actions, and Apple Shortcuts, but those are separate integration approaches rather than additional MCP tools.

Limitations and notes

Write access is scope-controlled, and product creation can be blocked by plan quotas. The README documents account and organization protections, two-factor authentication checks during OAuth approval, refresh-token rotation, reuse detection, rate limits, and audit logging. These controls affect authorization and API behavior rather than adding agent capabilities.

The local MCP package requires a harukibox token. Developers choosing the remote endpoint need to implement or use the documented OAuth and HTTP access flow. The repository identifies MIT as the project license.