Skip to content

About

MCP server for Japanese address normalization and GSI elevation lookup. No API keys required.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿ—พ mcp-server-japan-atlas

An MCP server that gives Claude a deep understanding of Japanese geography โ€” normalizing addresses, resolving coordinates, and querying official GSI elevation data, all without requiring any API keys.

License: MIT Node.js MCP Compatible Tests


Why This Exists

Japanese addresses are famously difficult for software systems โ€” and even more so for AI models.

The core problems:

Problem Example
Non-Western ordering (large โ†’ small) Prefecture โ†’ City โ†’ Ward โ†’ Block โ†’ Building
Multiple valid representations 1-2-3 vs ๏ผ‘ไธ็›ฎ๏ผ’็•ช๏ผ“ๅท vs ไธ€ไธ็›ฎไบŒ็•ชๅœฐไธ‰ๅท
No standardized delimiter Spaces, commas, newlines, or nothing at all
Kanji ambiguity ๅธ‚ (city) vs ๅŒบ (ward) vs ็”บ (town) vs ๆ‘ (village)
Postal codes intermixed ใ€’150-0043 ๆฑไบฌ้ƒฝๆธ‹่ฐทๅŒบ้“็Ž„ๅ‚1-2-3

When a user tells Claude "find me restaurants near ๆธ‹่ฐทๅŒบ้“็Ž„ๅ‚1-2-3", Claude cannot natively resolve that to coordinates, validate the address is real, or understand its elevation context (e.g., for flood-risk queries).

mcp-server-japan-atlas bridges this gap by connecting Claude directly to official Japanese public APIs โ€” turning unstructured Japanese address text into precise, structured geospatial data in real time.


Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                        Claude (LLM)                         โ”‚
โ”‚              "What's near ๆฑไบฌ้ƒฝๆธ‹่ฐทๅŒบ้“็Ž„ๅ‚1?"              โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                        โ”‚ MCP Protocol (stdio JSON-RPC)
                        โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚              mcp-server-japan-atlas (this server)           โ”‚
โ”‚                                                             โ”‚
โ”‚  Tool: normalize_jp_address          Tool: get_gsi_geo_context โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
โ”‚  โ”‚  1. Input validation โ”‚            โ”‚  1. Coord validation โ”‚ โ”‚
โ”‚  โ”‚  2. Regex parse      โ”‚            โ”‚  2. Japan bounds checkโ”‚ โ”‚
โ”‚  โ”‚  3. GSI Address APIโ†’ โ”‚            โ”‚  3. GSI DEM API call โ”‚ โ”‚
โ”‚  โ”‚     lat/lon          โ”‚            โ”‚  4. Elevation + hsrc โ”‚ โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚                                  โ”‚
           โ–ผ                                  โ–ผ
  GSI Address Search API            Japan GSI Elevation API
  (msearch.gsi.go.jp)               (cyberjapandata2.gsi.go.jp)
  No key required                   No key required
  Japan Post address DB             Official DEM, 5m/10m resolution

Tools

normalize_jp_address

Parses a raw Japanese address string into structured components and attempts geocoding.

Input:

{
  "address": "ใ€’150-0043 ๆฑไบฌ้ƒฝๆธ‹่ฐทๅŒบ้“็Ž„ๅ‚1-2-3"
}

Output:

{
  "success": true,
  "data": {
    "original": "ใ€’150-0043 ๆฑไบฌ้ƒฝๆธ‹่ฐทๅŒบ้“็Ž„ๅ‚1-2-3",
    "prefecture": "ๆฑไบฌ้ƒฝ",
    "city": "ๆธ‹่ฐทๅŒบ",
    "ward": "",
    "block": "1-2-3",
    "remainder": "้“็Ž„ๅ‚",
    "latitude": 35.6591,
    "longitude": 139.6981,
    "source": "gsi-address-search"
  },
  "note": "Geocoordinates resolved. Use get_gsi_geo_context to enrich with elevation."
}

Error handling: Returns structured error objects with codes INVALID_INPUT, ADDRESS_NOT_FOUND โ€” never throws raw stack traces to the LLM.


get_gsi_geo_context

Returns the official elevation at any point in Japan using the GSI (ๅ›ฝๅœŸๅœฐ็†้™ข) Digital Elevation Model API.

Input:

{
  "latitude": 35.6591,
  "longitude": 139.6981
}

Output:

{
  "success": true,
  "data": {
    "latitude": 35.6591,
    "longitude": 139.6981,
    "elevation": 37.5,
    "unit": "metres",
    "hsrc": "5m"
  },
  "note": "Elevation is 37.5 m above sea level. Data source: 5m."
}

Data source codes (hsrc): 5m = 5m-resolution DEM, 10m = 10m-resolution DEM, none = sea/no data.


Installation

Prerequisites

  • Node.js 18 or higher
  • Claude Desktop (or any MCP-compatible client)

Install via npx (recommended)

No cloning or building required. Just add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

npx downloads and runs the latest version automatically โ€” no manual steps needed.

Install from source (for development)

git clone https://github.com/b84330808/mcp-server-japan-atlas
cd mcp-server-japan-atlas
npm install
npm run build

Then point your config to the built file:

{
  "mcpServers": {
    "japan-atlas": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-japan-atlas/dist/index.js"]
    }
  }
}

Restart Claude Desktop after saving. To verify the server loaded:

  1. Click the + button in the bottom-left of the chat input area
  2. Select Connectors
  3. You should see japan-atlas listed with a blue toggle (enabled)

If the toggle is grey, click it to enable. No hammer icon โ€” the server lives in the Connectors menu.


Example Prompts

Once installed, try these prompts in Claude Desktop:

Address normalization:

"Parse this address for me: ๆฑไบฌ้ƒฝๆธ‹่ฐทๅŒบ้“็Ž„ๅ‚1-2-3"

"I have a Japanese address written messily: ใ€’150-0043 ๆฑไบฌ้ƒฝ ๆธ‹่ฐทๅŒบ ้“็Ž„ๅ‚ 1ไธ็›ฎ2็•ช3ๅท. Can you give me the structured components and coordinates?"

"Is this a valid Japanese address? ๅคง้˜ชๅบœๅคง้˜ชๅธ‚ๅŒ—ๅŒบๆข…็”ฐ๏ผ‘ไธ็›ฎ๏ผ‘๏ผ“็•ชๅœฐ"

Elevation & geospatial context:

"What is the elevation at the coordinates of Shibuya Station (35.6580, 139.7016)?"

"I'm looking at a building at lat 35.3607, lon 138.7274 โ€” what's the elevation? Is this likely to be near Mount Fuji?"

Chained workflow:

"Normalize the address ไบฌ้ƒฝๅบœไบฌ้ƒฝๅธ‚ไธญไบฌๅŒบๆฒณๅŽŸ็”บ้€š and then tell me the elevation at those coordinates."

"I'm building a flood-risk report for ๆจชๆตœๅธ‚่ฅฟๅŒบใฟใชใจใฟใ‚‰ใ„2ไธ็›ฎ. What are the structured address components and how high above sea level is this area?"

Error handling demonstration:

"What happens if I give you a fake address like ใ‚ใ„ใ†ใˆใŠใ‹ใใใ‘ใ“?"

"Try to get the elevation of London, UK using the Japan GSI tool."


Development

# Type-check without building
npm run lint

# Run tests
npm test

# Run tests with coverage report
npm run test:coverage

# Build for production
npm run build

Project Structure

mcp-server-japan-atlas/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ index.ts        # MCP server, tool registry & dispatch
โ”‚   โ”œโ”€โ”€ address.ts      # Address normalization logic + GSI Address Search API
โ”‚   โ”œโ”€โ”€ elevation.ts    # GSI elevation API client
โ”‚   โ””โ”€โ”€ types.ts        # Shared TypeScript interfaces
โ”œโ”€โ”€ tests/
โ”‚   โ””โ”€โ”€ index.test.ts   # 26 unit tests (Jest + ts-jest)
โ”œโ”€โ”€ dist/               # Compiled output (generated)
โ”œโ”€โ”€ tsconfig.json
โ”œโ”€โ”€ tsconfig.test.json
โ””โ”€โ”€ package.json

Error Architecture

All tool errors are returned as structured MCP content (not thrown exceptions), so Claude always receives a readable explanation:

// Every error has a machine-readable code + human-readable message
{
  "success": false,
  "error": {
    "code": "OUT_OF_COVERAGE",
    "message": "Coordinates (51.5074, -0.1278) are outside Japan's coverage area..."
  }
}

Error codes:

Code Trigger
INVALID_INPUT Empty string, non-Japanese text, input > 300 chars
ADDRESS_NOT_FOUND No prefecture recognized, API returns nothing
OUT_OF_COVERAGE Coordinates outside Japan bounding box
INVALID_COORDINATES NaN, Infinity, or out-of-range lat/lon
API_TIMEOUT External API did not respond within 10 seconds
API_ERROR External API returned HTTP error
NETWORK_ERROR Network-level failure

Data Sources

Source URL License Used for
GSI Address Search https://msearch.gsi.go.jp Public domain Address โ†’ lat/lon (GeoJSON)
Japan GSI DEM https://cyberjapandata2.gsi.go.jp Public domain Elevation data

Both APIs are free, require no authentication, and are operated by the Ministry of Land, Infrastructure, Transport and Tourism (ๅ›ฝๅœŸๅœฐ็†้™ข).


Contributing

Pull requests are welcome. Please ensure:

  1. npm run lint passes (no TypeScript errors)
  2. npm test passes (all 26 tests green)
  3. New features include corresponding tests
  4. Error handling follows the existing pattern (structured McpErrorPayload)

License

MIT โ€” see LICENSE.


Built for the Anthropic "Claude for OSS" program. Powered by official Japanese government open data.

About

MCP server for Japanese address normalization and GSI elevation lookup. No API keys required.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages