Israel Hiking MCP

An unofficial, non-commercial, read-only MCP server exposing Israel Hiking Map / Mapeak hiking data to LLM hosts.

Status: early scaffolding (PR 2 of 9). The server speaks MCP over stdio and has its HTTP foundation — settings, typed errors, a cached and rate-capped upstream client — but still exposes only a placeholder ping tool. Place search, route search, route details, POIs along a route, and routing all land in later PRs.

See LICENSE-NOTICE.md before using any output — the upstream data is CC BY-NC-SA 3.0 (non-commercial, share-alike) and ODbL.

Requirements

• Python 3.11+

• uv

Related MCP server: MCP Server - Placeholder Implementation

Setup

uv sync

Run

uv run israel-hiking-mcp

The server communicates over stdio and produces no stdout output of its own — stdout is reserved for the JSON-RPC message stream. Logs go to stderr; set IHM_LOG_LEVEL=DEBUG for verbose output.

Tests

uv run pytest

The suite runs fully offline.

Try it with MCP Inspector

npx @modelcontextprotocol/inspector uv run israel-hiking-mcp

Set the working directory to this repository, connect, open the Tools tab, and call ping.

Use from an MCP host

Claude Desktop (claude_desktop_config.json) or any generic MCP client:

{
  "mcpServers": {
    "israel-hiking": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/israel-hiking-mcp", "run", "israel-hiking-mcp"]
    }
  }
}

Tools

Configuration

All settings are environment variables, read once at startup — an invalid value stops the server with a message naming the variable, rather than failing later inside a tool call.

Request behaviour

Every upstream request is a GET with a timeout, capped concurrency, and a short-lived in-memory cache. A request is retried once, and only after a timeout, a connection failure, or a 5xx; 4xx responses are never retried and failures are never cached. This is a personal-scale tool pointed at a volunteer-run service — please keep it that way.

Error codes

Tool failures arrive as MCP errors whose text begins with a stable code:

invalid_input · place_not_found · route_not_found · unsupported_source · search_area_too_large · geometry_too_large · upstream_timeout · upstream_unavailable · upstream_schema_changed · rate_limited

upstream_timeout, upstream_unavailable and rate_limited are transient; the rest will not be fixed by retrying. Upstream response bodies, URLs and tracebacks are never included in the message — those go to the stderr log.