mcp-server-postcode

MCP (Model Context Protocol) server for searching Japanese postcodes, addresses, prefectures, buildings, and offices via the postcode.teraren.com public API.

Tools

| Tool | Description | |------|-------------| | search_postcodes | Search postcodes by address keyword (e.g. 六本木ヒルズ) | | get_postcode | Get address details for a 7-digit postcode | | get_postcode_text | Get address as plain text (with optional part filter) | | list_prefectures | List all 47 prefectures | | get_prefecture_cities | List cities in a prefecture by code (1-47) | | get_city_postcodes | List postcodes in a specific city | | search_buildings | Search buildings with floor-specific postcodes | | get_building | Get a building's floor-by-floor postcode list | | search_offices | Search office-specific postcodes (事業所郵便番号) | | get_office | Get an office-specific postcode by its 7-digit code |

Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "postcode": {
      "command": "npx",
      "args": ["-y", "mcp-server-postcode"]
    }
  }
}

Claude Code

claude mcp add postcode -- npx -y mcp-server-postcode

Manual / Other MCP Clients

npx -y mcp-server-postcode

The server communicates via stdio using the MCP protocol.

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | POSTCODE_API_URL | https://postcode.teraren.com | Base URL for the API |

Examples

Once configured, you can ask your AI assistant:

• "郵便番号 1066137 の住所を教えて" (Get address for postcode 1066137)
• "六本木ヒルズの郵便番号を検索して" (Search postcode for Roppongi Hills)
• "東京都の市区町村一覧を見せて" (Show cities in Tokyo)
• "港区の郵便番号一覧を出して" (List postcodes in Minato-ku)
• "タワーが名前に含まれるビルを検索して" (Search buildings with "tower" in the name)
• "日本郵便の事業所郵便番号を調べて" (Look up Japan Post's office postcode)

Development

npm install
npm run build
npm start

API

This MCP server wraps the public REST API at https://postcode.teraren.com. No API key or registration required. See API documentation for details.

License

CC-BY-SA-4.0