Skip to main content
Glama

RefConvMCP

An MCP server that takes Ordnance Survey (British National Grid) grid references, such as SU 123 456, converts them to lat/long, and fetches Google Street View images for that spot.

"Show me Street View at NN 166 712, looking all four ways"

Tools

Tool

What it does

Cost

gridref_to_latlon

Grid ref → WGS84 lat/long, easting/northing and a Google Maps link

free, offline

latlon_to_gridref

Lat/long → grid ref (2–10 figures)

free, offline

streetview_coverage

Checks for a panorama near a grid ref and returns its capture date and distance/bearing to the point

free (metadata endpoint)

streetview_from_gridref

Returns Street View image(s) inline and can also save them as JPEGs

billed per image by Google

Grid reference formats

  • Lettered, 0–10 digits: SU, SU1245, SU 123 456, su123456, NN 16650 71250

  • Numeric easting/northing in metres: 412300,145600

A grid reference is a square: 6 figures is 100 m and 8 figures is 10 m. The server uses the centre of the square and then finds the nearest outdoor Street View panorama within radius_m (default 100 m). By default it returns one image, taken from that panorama and looking towards the grid ref point. Use views=4 to get all-round coverage, or set heading, pitch and fov yourself.

The conversion uses pyproj (EPSG:27700 → EPSG:4326).

Related MCP server: mcp-postcodes

How it works

"SU 123 456"
   │  1. parse grid ref        (gridref.py)
   ▼
easting 412350, northing 145650   (centre of the 100 m square)
   │  2. reproject OSGB36 → WGS84   (pyproj, EPSG:27700 → EPSG:4326)
   ▼
51.2099, -1.8246
   │  3. find nearest panorama   (Street View metadata API, free)
   ▼
pano_id, panorama lat/long, capture date
   │  4. work out the camera heading from the panorama to the point
   │  5. fetch image(s) by pano_id    (Street View Static API, billed)
   ▼
JPEG(s) returned to the model as MCP image content and saved to disk
  1. Parsing a grid reference (src/refconv_mcp/gridref.py). The two letters name a 100 km square on the British National Grid. The letter I isn't used, and the first letter picks a 500 km block. The server turns the letters into the square's south-west corner in metres. The digits split into an easting half and a northing half. Their scale depends on how many there are: 6 figures means each digit pair counts in 100 m steps. The server then adds half a square to get the centre. You can also enter an easting/northing in metres directly.

  2. Converting to lat/long. Easting and northing are on the OSGB36 datum with a Transverse Mercator projection. GPS and Google use WGS84. pyproj does the datum shift and projection, which is accurate to a few metres. That's well inside a 6-figure square. latlon_to_gridref does the same steps in reverse.

  3. Finding a panorama (src/refconv_mcp/streetview.py). The Street View metadata endpoint is free. It returns the nearest outdoor panorama within radius_m, or ZERO_RESULTS if there isn't one. That way the server never pays for an image that doesn't exist.

  4. Aiming the camera. Panoramas are usually on a road, not on the grid point itself. The server calculates the compass bearing from the panorama to the point, so the default view looks at the place you asked about. With views=N, the N headings are spread evenly around 360°, starting from that bearing.

  5. Fetching images. Each view is requested by pano_id, so every image comes from the same panorama. The images go back to the model as MCP image content. They're also saved as <gridref>_<timestamp>_h<heading>.jpg in REFCONV_OUTPUT_DIR.

The server (src/refconv_mcp/server.py) uses the official MCP Python SDK (FastMCP) and talks to the client over stdio.

Setup

1. Google API key

  1. In Google Cloud Console, create or choose a project and enable billing. Street View has a monthly free tier.

  2. Enable the Street View Static API under APIs & Services → Library.

  3. Create an API key under APIs & Services → Credentials. Restrict it to the Street View Static API.

2. Install

Requires uv.

git clone https://github.com/scottejames/RefConvMCP.git
cd RefConvMCP
uv sync
cp .env.example .env && chmod 600 .env   # then put your key in .env

3. Register with Claude Code

claude mcp add --scope user refconv -- "$PWD/run.sh"

Keeping the API key out of git

  • The key lives only in .env. That file is gitignored, so it is never committed. .env.example is the committed template.

  • run.sh sources .env and then starts the server. Claude Code is registered against run.sh, so the key is not stored in ~/.claude.json either.

  • If an API error message contains the key, the server redacts it before returning the message to the model.

  • Other MCP clients can skip run.sh and set GOOGLE_MAPS_API_KEY in the environment directly.

Variable

Required

Purpose

GOOGLE_MAPS_API_KEY

yes (Street View tools only)

Google key with the Street View Static API enabled

REFCONV_OUTPUT_DIR

no

Where images are saved (run.sh defaults to ./streetview_images, which is gitignored)

Development

uv run pytest

Licence

MIT. Street View imagery is © Google and subject to the Google Maps Platform Terms.

Available Tools

4 tools
gridref_to_latlonA

Convert an OS grid reference to WGS84 latitude/longitude.

Args: grid_ref: e.g. "SU 123 456", "NN166712", "TQ3080" or numeric "412300,145600". centre: return the centre of the referenced square (True) or its SW corner (False).

Inputs: grid_ref (required), centre.

latlon_to_gridrefA

Convert WGS84 latitude/longitude to an OS grid reference.

Args: lat: latitude in decimal degrees. lon: longitude in decimal degrees. digits: total figures in the reference (2-10, even). 6 = 100 m precision.

Inputs: lat (required), lon (required), digits.

streetview_coverageA

Check whether Google Street View has a panorama near a grid reference.

Uses the free metadata endpoint, so it costs nothing. Returns the panorama location, capture date, and distance/bearing to the grid reference point.

Args: grid_ref: OS grid reference, e.g. "SU 123 456". radius_m: how far from the point to search for a panorama (metres).

Inputs: grid_ref (required), radius_m.

streetview_from_gridrefA

Fetch Google Street View image(s) for an OS grid reference.

Finds the nearest outdoor panorama within radius_m of the centre of the grid square, then returns the image(s). By default one image is taken looking from the panorama towards the grid reference point.

Args: grid_ref: OS grid reference, e.g. "SU 123 456" or "NN166712". views: number of images spread evenly around 360 deg (1-8). 4 gives N/E/S/W-style coverage. heading: compass heading of the first view in degrees. Default: towards the point (or 0 if the panorama is on top of it). pitch: up/down camera angle, -90 to 90. fov: horizontal field of view in degrees, 10-120. radius_m: search radius for the nearest panorama in metres. size: image size "WxH", max 640x640. save: also save JPEGs to REFCONV_OUTPUT_DIR and return their paths.

Inputs: grid_ref (required), fov, save, size, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation4/5

    The conversion pair (gridref_to_latlon vs latlon_to_gridref) is unambiguous, distinguished by direction and argument names. The two Street View tools are mostly distinct (free metadata probe vs image retrieval), but streetview_coverage overlaps with the panorama-lookup step already embedded in streetview_from_gridref, so an agent may wonder which to call first.

    Naming Consistency4/5

    All names use snake_case and the two conversion tools follow a clean symmetric 'a_to_b' pattern, with streetview_ prefix grouping the imagery tools. Minor deviation: 'coverage' is a noun while the others are action/prepositional phrases, but the set is still easily readable.

    Tool Count4/5

    Four tools is tight and appropriate for a narrow conversion-plus-imagery utility, with each tool mapping to a distinct step. It is slightly on the lean side, and streetview_coverage is partially redundant with the lookup inside streetview_from_gridref.

    Completeness4/5

    Both conversion directions plus a coverage check and image retrieval cover the core workflow end to end. Gaps are minor: no batch conversion, no alternative datums/other national grids, and no reverse lookup of a panorama back to coordinates.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers