How do I use geojp-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@geojp-mcp What's the address for 35.681236, 139.767125?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

geojp-mcp

by 55tarkun

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

geojp-mcp

日本語版 README はこちら

An MCP (Model Context Protocol) server that exposes two Japan-specific geodata APIs as tools for AI agents (Claude Code, Claude Desktop, and other MCP clients):

ChibanJP — coordinates → chiban (地番, the official cadastral lot number recorded at Japan's Legal Affairs Bureau). Chiban rarely maps predictably to a residential address (住居表示) and is not exposed by most general-purpose geocoders.
ReverseGeoJP — coordinates ⇄ Japanese address (reverse geocoding / forward geocoding).

Why chiban?

Japan uses two independent addressing systems: the residential address (住居表示) that appears on maps and mail, and the chiban — the cadastral lot number used in property registries, land transactions, and legal documents. The two do not follow a predictable pattern, so converting between them requires a dedicated lookup against registry map data, not a lookup table.

Chiban matters for real estate due diligence, land transaction platforms, and any workflow that touches Japan's registry system — a growing need as foreign investment in Japanese real estate rises. Most global geocoding APIs do not source chiban directly from registry map data, which is why this exists as a standalone tool.

Related MCP server: townshipamerica-mcp

Tools

Tool	Backing API	Input	Returns
`get_parcel`	ChibanJP `/parcel`	`lat`, `lon`	Chiban (cadastral lot number), ōaza/aza, municipality, and survey precision class for the containing parcel
`reverse_geocode`	ReverseGeoJP `/reverse`	`lat`, `lon`	Nearest residential address (prefecture, municipality, district, postal code)
`geocode`	ReverseGeoJP `/geocode`	`address`	Up to 10 candidate locations for a partial address match
`lookup_location`	Both, in parallel	`lat`, `lon`	Address and chiban together in one call (an orchestration example — succeeds with address-only if the point falls outside ChibanJP's current coverage)

All tools share a single API key. Get one at reversegeojp.com.

Two ways to run it

The tool definitions live in src/tools.ts and are shared by both entry points:

Local (stdio) — src/index.ts. Your MCP client launches it as a child process on your machine. One user, one API key.
Remote (HTTP, Cloudflare Workers) — src/worker.ts. Already deployed at https://mcp.reversegeojp.com; anyone can connect with their own API key, no build step required.

Setup (local/stdio)

npm install -g geojp-mcp

or, from source:

npm install
npm run build

The server reads the API key from the GEOJP_API_KEY environment variable. You normally don't run it directly — your MCP client starts it as a subprocess (see below).

Register with Claude Code

claude mcp add --scope user geojp -e GEOJP_API_KEY=your-api-key-here -- npx geojp-mcp

--scope user makes it available across all projects on your machine (omit it to register for the current project only). Verify with claude mcp list.

Argument order matters: -e/--env accepts multiple values, so it will swallow subsequent arguments if placed before the server name. Keep the order: add, then the server name, then -e.

Or configure manually in .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "geojp": {
      "type": "stdio",
      "command": "npx",
      "args": ["geojp-mcp"],
      "env": {
        "GEOJP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Register with Claude Desktop

Add the same block to the mcpServers section of claude_desktop_config.json, then restart Claude Desktop. Four tools (reverse_geocode, geocode, get_parcel, lookup_location) become available.

Setup (remote/HTTP)

Connect directly to the hosted server with your own API key — no install or build required:

claude mcp add --scope user --transport http geojp-remote https://mcp.reversegeojp.com --header "Authorization: Bearer your-api-key-here"

Health check: GET https://mcp.reversegeojp.com/health.

Remote server design notes

No bindings, stateless: the Worker holds no session state and uses no Durable Objects. Every call reads the API key from the Authorization header and proxies straight through to the ReverseGeoJP/ChibanJP production APIs. This avoids the paid Workers plan that Durable Objects require, so it runs on the same free plan as reverse-geo-jp/chibanjp with no added infrastructure cost (the more common McpAgent pattern from agents-sdk assumes Durable Objects and a paid plan).
Web Standards transport: uses @modelcontextprotocol/sdk's WebStandardStreamableHTTPServerTransport, since the Node-only StreamableHTTPServerTransport depends on http.IncomingMessage/ServerResponse, which don't exist in the Workers runtime.
Gotcha: reversegeojp-client/chibanjp-client default to holding a bare, unbound fetch (this.fetchImpl = options.fetch ?? fetch), which throws "Illegal invocation" on Cloudflare Workers. Fixed by passing an explicitly-bound fetch into the client constructor options in createGeojpMcpServer() (see boundFetch in src/tools.ts). Also fixed upstream in geojp-api-clients v0.1.1 (fetch.bind(globalThis)); geojp-mcp depends on that version, and keeps the local boundFetch as a harmless fallback.

Deploy / local dev

npm run worker:dev     # local wrangler dev server (http://127.0.0.1:8787 etc.)
npm run worker:check   # typecheck against the Workers tsconfig only
npm run worker:deploy  # deploy to production

Smoke test (no API key required — wiring check only)

npm run smoke-test

Starts the server with a dummy key and confirms the tool list loads and a real API call correctly returns an invalid_api_key error.

Why this exists

ReverseGeoJP/ChibanJP were already running as APIs meant to be called directly by developers reading the docs. This project exposes them as MCP tools so AI agents can discover and call them automatically — reusing the existing production infrastructure while building hands-on MCP/agent-integration experience.

License

MIT

Available Tools

4 tools

geocodeGeocode (Japanese address -> lat/lon candidates)AInspect

日本語の住所文字列（部分一致）から、候補となる町丁目と緯度経度を最大10件返します。ReverseGeoJP APIを使用。

ParametersJSON Schema

Name	Required	Description	Default
`address`	Yes	検索する住所文字列

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It usefully reveals that partial matches are allowed, returns up to 10 candidates, and uses the ReverseGeoJP API. However, it does not mention error handling, rate limits, or the read-only nature, which are relevant but perhaps less critical for a simple lookup tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the core purpose and includes key limitations (partial match, max 10). Every word adds value, and there is no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, the description adequately explains the return value: town district and lat/lon candidates, capped at 10. It could be more complete by mentioning coordinate format or failure behavior, but it covers the essential information needed to understand the tool's function.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the sole parameter 'address' as '検索する住所文字列' (address string to search), so the baseline is 3. The description adds meaningful semantics by specifying that the address must be a Japanese string and supports partial matching, which goes beyond the generic schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: converting a Japanese address string into candidate town districts (町丁目) with latitude/longitude, returning up to 10 results. It uses a specific verb '返します' (returns) and distinguishes from reverse_geocode by explicitly indicating direction from address to coordinates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives like reverse_geocode or lookup_location. It merely states what the tool does, leaving the agent to infer the appropriate context from the directionality implied by the name and title.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_parcelGet parcel (lat/lon -> chiban)AInspect

緯度経度から、その地点を含む筆の地番・大字・市区町村・測量精度区分を返します。ChibanJP APIを使用。対応エリアは東京都・大阪府・北海道・愛知県・神奈川県・兵庫県・福岡県・長野県の8都道府県のみ。

ParametersJSON Schema

Name	Required	Description	Default
`lat`	Yes	緯度
`lon`	Yes	経度

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It reveals the underlying API (ChibanJP) and the critical limitation of only covering 8 prefectures, which is essential behavior. It also lists the output fields. It does not mention error behavior (e.g., if the point is outside the supported area or not in a parcel), but the disclosed scope is a significant transparency win.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, with the primary action and return contents in the first sentence, and the API source and critical area limitation in the second. There is no filler, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter lookup, the description provides the key context: what is returned, the data source, and the geographic limitation. It does not detail error handling or coordinate system, but the simplicity of the tool and complete parameter schema mitigate that need. It is slightly below a 5 because error behavior for out-of-area points is unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully describes both parameters (lat and lon) with ranges and labels. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate per the guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the parcel number, 大字, city, and surveying accuracy for a point given lat/lon. This is a specific verb+resource combination and distinguishes itself from sibling geocoding tools by focusing on chiban data from the ChibanJP API.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists the eight supported prefectures, giving clear usage boundaries. However, it does not mention alternatives like reverse_geocode for general addresses or geocode for forward lookups, so it is not fully explicit about when to choose this over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_locationLookup location (lat/lon -> address + parcel, combined)AInspect

緯度経度から、住所（ReverseGeoJP）と地番（ChibanJP）をまとめて調べます。2つの独立したAPIを並行に呼び出して1回の結果に統合します。ChibanJPは対応8都道府県外だとnot_foundになる点に注意（住所側は取得できる場合があります）。

ParametersJSON Schema

Name	Required	Description	Default
`lat`	Yes	緯度
`lon`	Yes	経度

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well: it discloses that two independent APIs are called in parallel and integrated, and warns about the not_found behavior outside supported prefectures. It does not mention error handling or partial failure behavior, but the disclosed traits are valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loading the primary purpose and then adding a crucial caveat. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is moderately complex due to combining two APIs, and there is no output schema. While the description explains the parallel call and the not_found caveat, it does not describe the result structure or how partial failures are handled, leaving some ambiguity for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both lat and lon. The tool description adds no further parameter semantics, so the baseline of 3 is appropriate—the schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it looks up both an address (ReverseGeoJP) and a parcel number (ChibanJP) from latitude/longitude and combines them into one result. This distinguishes it from siblings like reverse_geocode and get_parcel, which handle each separately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is the combined alternative to calling reverse_geocode and get_parcel separately, and it provides a key usage caveat about ChibanJP only supporting 8 prefectures. However, it does not explicitly state when to choose this over individual tools or provide exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reverse_geocodeReverse geocode (lat/lon -> Japanese address)AInspect

緯度経度から最も近い町丁目の住所（都道府県・市区町村・町域・郵便番号）を返します。ReverseGeoJP APIを使用。境界内判定ではなく最近傍点を返す点に注意。

ParametersJSON Schema

Name	Required	Description	Default
`lat`	Yes	緯度
`lon`	Yes	経度

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden for behavioral disclosure. It usefully notes that results are based on the nearest point rather than boundary containment and mentions the underlying ReverseGeoJP API. However, it does not address failure cases, coordinate datum, result distance limits, or API error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences, front-loads the core behavior, and includes a valuable caveat. Every phrase adds information; there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description does list the essential return components (prefecture, municipality, town area, postal code) and highlights the nearest-point behavior. It lacks some edge-case details and explicit sibling differentiation, but it is sufficiently complete for a simple reverse-geocoding tool with two well-specified parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides full coverage for lat and lon, including ranges and brief Japanese labels. The description adds that these coordinates are used to find the nearest town address, but offers no extra detail about precision, units, or coordinate system, so it does not exceed the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool converts latitude/longitude into the nearest town-level Japanese address, listing specific components (prefecture, municipality, town area, postal code). This specific verb+resource statement distinguishes it from sibling tools like geocode, which handles the forward direction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (reverse geocoding from coordinates) via the title and the note about returning the nearest point rather than a boundary match. However, it does not explicitly state when to use this tool versus alternatives like geocode or get_parcel, nor does it name alternative tools for forward geocoding or parcel-level lookup.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Aug 7, 2026
- First observedgeocode
- First observedget_parcel
- First observedlookup_location
- First observedreverse_geocode

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-08-07 18:55 across 4 tools

Disambiguation4/5

Each tool has a distinct purpose: forward geocoding, reverse geocoding, parcel lookup, and a combined reverse+parcel lookup. The combined lookup overlaps slightly with reverse_geocode and get_parcel, but the description clearly explains it as a composite, minimizing ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (reverse_geocode, geocode, get_parcel, lookup_location) using lowercase and underscores. While verbs vary, the naming style is uniform and predictable.

Tool Count5/5

With just 4 tools, the server is tightly scoped to Japanese geocoding and parcel lookup. Each tool serves a clear and distinct need, making the count appropriate without being thin or bloated.

Completeness5/5

The tool set covers the core domain operations: forward geocoding, reverse geocoding, parcel lookup, and a combined convenience method. No significant functional gaps are apparent; limitations like 8-prefecture parcel coverage are data constraints, not missing tool capabilities.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

UnifAPIOAuth
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2
OnceAsk A
io.github.rsb6061
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
Customer Data Platforms Search Location Services
41
IPinfo A
io.github.ipinfo
Official IPinfo MCP Server - IP intelligence tools for AI assistants
Location Services Security
61
mcp-aichatOAuth
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2

Related MCP Servers

Zipcode Search MCP Server
Search Location Services
rooking-oss
A
license
Not graded
quality
D
maintenance
Provides Japanese postal code to address lookup functionality that can be integrated with AI assistants and other MCP clients.
Updated a year ago (2025-06-10 10:36 UTC)
3
MIT
townshipamerica-mcpofficial
Location Services Open Data
townshipamerica
A
license
Not graded
quality
F
maintenance
MCP server for converting PLSS legal descriptions to GPS coordinates and vice versa, enabling AI agents to work with U.S. Public Land Survey System data.
Updated 3 months ago (2026-06-22 19:45 UTC)
MIT
houjin-bangou-api-mcp
Government Data Search
yamayued
A
license
B
quality
D
maintenance
MCP server for the Japan National Tax Agency Corporate Number API, enabling corporate number lookup and search via local AI clients.
Updated 6 months ago (2026-03-13 04:22 UTC)
3
1
MIT
kenall-mcp
Location Services Search
knsh14
A
license
B
quality
D
maintenance
MCP server that provides access to the Kenall postal code API for Japanese address lookups, enabling lookup by postal code and search by address.
Updated a year ago (2025-08-01 08:59 UTC)
2
MIT

geojp-mcp

Why chiban?

Tools

Two ways to run it

Setup (local/stdio)

Register with Claude Code

Register with Claude Desktop

Setup (remote/HTTP)

Remote server design notes

Deploy / local dev

Smoke test (no API key required — wiring check only)

Why this exists

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

townshipamerica-mcpofficial