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.
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.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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
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.
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.
- Node.js 18 or higher
- Claude Desktop (or any MCP-compatible client)
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.
git clone https://github.com/b84330808/mcp-server-japan-atlas
cd mcp-server-japan-atlas
npm install
npm run buildThen 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:
- Click the
+button in the bottom-left of the chat input area - Select Connectors
- You should see
japan-atlaslisted with a blue toggle (enabled)
If the toggle is grey, click it to enable. No hammer icon โ the server lives in the Connectors menu.
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."
# 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 buildmcp-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
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 |
| 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 (ๅฝๅๅฐ็้ข).
Pull requests are welcome. Please ensure:
npm run lintpasses (no TypeScript errors)npm testpasses (all 26 tests green)- New features include corresponding tests
- Error handling follows the existing pattern (structured
McpErrorPayload)
MIT โ see LICENSE.
Built for the Anthropic "Claude for OSS" program. Powered by official Japanese government open data.