Overview

This repository implements an MCP (Model Context Protocol) server that integrates the Walk Score API to surface pedestrian, transit, and bicycle friendliness for a given location. It wraps Walk Score’s endpoints and exposes developer-friendly HTTP tools that are suitable for both direct use in applications and for connecting to language models or other agents that consume MCP-style tool metadata.

By centralizing Walk Score calls behind a small MCP server, you get a stable local interface for geolocation scoring, consistent JSON responses, and simple authentication via environment variables. This is useful for real-estate apps, route planners, urban analysis dashboards, or any project that needs to enrich locations with walkability, transit, and bikeability insights.

GitHub: https://github.com/jackyang25/geolocation-mcp-server

Features

Simple HTTP endpoints for Walk Score, Transit Score, and Bike Score lookups
MCP-friendly tool metadata to integrate with LLM agents or tool runners
Environment-configurable API key and server port
Minimal wrapper that normalizes Walk Score JSON responses
Example usage with curl and sample request/response payloads

Installation / Configuration

Prerequisites: Node.js (14+), npm or Docker.

Clone and install:

git clone https://github.com/jackyang25/geolocation-mcp-server.git
cd geolocation-mcp-server
npm install

Environment variables (create a .env file in the project root):

WALK_SCORE_API_KEY=your_walkscore_api_key_here
PORT=3000

Start the server:

npm run start
# or for development
npm run dev

Run with Docker (example):

docker build -t geolocation-mcp-server .
docker run -e WALK_SCORE_API_KEY=your_key -p 3000:3000 geolocation-mcp-server

Replace your_walkscore_api_key_here with the API key you obtain from Walk Score (https://www.walkscore.com/professional/api.php).

Available Tools / Resources

This server exposes three primary tools/endpoints. Each accepts latitude and longitude (and optional address) and returns normalized JSON from the Walk Score APIs.

Endpoints

Method	Path	Query parameters	Description
GET	/walkscore	lat, lon, address (optional)	Returns walk score and associated data
GET	/transitscore	lat, lon, address (optional)	Returns transit score and transit details
GET	/bikescore	lat, lon, address (optional)	Returns bike score and relevant metadata

Example: GET /walkscore?lat=47.608&lon=-122.329

Tool manifest (MCP-style) — example JSON you can feed to an LLM/tool runner:

{
  "name": "walk_score",
  "description": "Retrieve Walk Score for a location (lat, lon or address).",
  "parameters": {
    "type": "object",
    "properties": {
      "lat": { "type": "number" },
      "lon": { "type": "number" },
      "address": { "type": "string" }
    },
    "required": ["lat", "lon"]
  },
  "endpoint": "/walkscore"
}

Example Requests

Simple curl to get a walk score:

curl "http://localhost:3000/walkscore?lat=47.608013&lon=-122.335167"

Sample JSON response (normalized):

{
  "status": "ok",
  "score": 92,
  "description": "Walker's Paradise",
  "walkscore_url": "https://www.walkscore.com/score/...",
  "details": {
    "transit": { "has_transit": true, "transit_score": 84 },
    "bike": { "bike_score": 78 }
  }
}

If using programmatic fetch in Node/Browser:

const res = await fetch('http://localhost:3000/transitscore?lat=47.6&lon=-122.33');
const json = await res.json();
console.log(json);

Use Cases

Real estate listings: Show walk, transit, and bike scores on property pages to help buyers evaluate neighborhood mobility.
Route planning and delivery: Combine walk/transit/bike scores with routing data to choose optimized pickup/dropoff zones.
Urban analytics and planning: Batch-score many coordinates to map mobility heatmaps and identify underserved areas.
Conversational agents: Provide an LLM with the MCP tool manifest so the model can call the server to answer questions like “How walkable is 1600 Pennsylvania Ave?” in real time.
Site selection: Use scores to filter candidate locations for retail, coworking, or service deployment.

Notes and Best Practices

Respect Walk Score API terms and rate limits. This wrapper does not change upstream rate limits.
Cache results where appropriate for batch analyses to reduce API calls and latency.
Validate lat/lon inputs and handle geocoding server-side if starting from a plain address.
Use HTTPS and secure storage for your WALK_SCORE_API_KEY in production environments.

For full source, examples, and any updates, see the project on GitHub: https://github.com/jackyang25/geolocation-mcp-server.

Geolocation MCP Server WalkScore Walk, Transit, Bike Scores