Overview

This MCP (Model Context Protocol) server wraps the Foursquare Places API and exposes it as a set of tools an LLM-based agent can call. It translates structured tool calls into authenticated Foursquare requests and returns normalized, machine-friendly responses so an agent can recommend venues (restaurants, attractions, shops, etc.) with up-to-date location and metadata.

Using an MCP server for Foursquare Places keeps your LLM agent stateless and focused on reasoning while delegating real-time place lookup, geocoding, and detail resolution to a dedicated service. This is useful for building travel assistants, local discovery bots, concierge systems, and any application that needs accurate venue suggestions across global markets.

Features

Search for venues by query, coordinates, and bounding boxes
Autocomplete / suggestions for partial place queries
Retrieve detailed place metadata (hours, categories, location, contact, URLs)
Photo and menu linking where available
Normalized JSON responses optimized for model consumption
Rate-limit and error handling wrapper around the Foursquare Places API
Simple MCP-compatible tool interface so LLM agents can invoke place lookups

Repository and source code: https://github.com/foursquare/foursquare-places-mcp

Installation / Configuration

Prerequisites:

Node.js 18+ (or the runtime stated in the repo)
A Foursquare Places API key (create or manage via Foursquare developer portal)

Clone and run locally:

git clone https://github.com/foursquare/foursquare-places-mcp.git
cd foursquare-places-mcp
npm install
npm run build   # if the project uses a build step
FOURSQUARE_API_KEY=your_foursquare_api_key npm start

Docker:

# Build image from the repository root
docker build -t foursquare-places-mcp .

# Run container exposing port 8080 (adjust as needed)
docker run -e FOURSQUARE_API_KEY=your_key -p 8080:8080 foursquare-places-mcp

Example .env file:

FOURSQUARE_API_KEY=your_foursquare_key_here
PORT=8080
LOG_LEVEL=info
CACHE_TTL_SECONDS=60

Configuration notes:

The server requires a valid Foursquare API key; set it via FOURSQUARE_API_KEY.
PORT controls the listening port. CACHE_TTL_SECONDS enables a short in-memory cache to reduce API calls.
If deploying behind TLS or a proxy, configure the proxy accordingly; the server itself typically serves over HTTP.

Available Tools / Resources

The MCP server exposes a set of tool endpoints (names may vary by implementation). Commonly provided tools include:

Tool name	Endpoint (example)	Description
search_places	POST /search	Find places by text query, ll (lat,long), limit, radius
autocomplete	POST /autocomplete	Provide suggestion completions for partial queries
get_place	GET /place/:fsq_id	Fetch detailed metadata for a place id
photos	GET /place/:fsq_id/photos	Get photo metadata for a place
categories	GET /categories	Retrieve Foursquare category taxonomy

Example request (search):

POST /search
Content-Type: application/json

{
  "query": "sushi",
  "ll": "40.7128,-74.0060",
  "limit": 5,
  "radius": 1000
}

Example response (abridged):

{
  "results": [
    {
      "fsq_id": "51234567",
      "name": "Sushi Place",
      "categories": ["Japanese", "Sushi"],
      "distance": 250,
      "location": {"lat": 40.7130, "lng": -74.0059, "address": "123 Example St"},
      "rating": 8.5
    }
  ]
}

Use Cases

Local assistant: An LLM agent recommends nearby cafes or co-working spots based on a user’s coordinates and stated preferences (quiet, Wi‑Fi, open late). The agent calls search and get_place to provide addresses, hours, and a short explanation.
Travel planner: For an itinerary, the agent queries attractions by city and category, ranks candidates by popularity or distance, and fetches photos and opening hours before presenting options.
Restaurant suggestions in chat: A conversational agent asks clarifying questions (cuisine, price, ambiance) and then invokes the MCP server to fetch a short list of vetted restaurants with addresses and booking links.
Agent fallbacks: If the LLM is uncertain about a place name or spelling, it can call autocomplete to surface candidate matches and then confirm with the user.

Tips and Troubleshooting

Rate limiting: Foursquare enforces rate limits. Use caching (CACHE_TTL_SECONDS) and sensible paging to avoid hitting limits.
API key scope: Ensure your Foursquare API key has Places access enabled.
Error handling: The server exposes clear HTTP status codes and error messages. On upstream errors, the MCP server normalizes responses so agents can gracefully retry or ask follow-up questions.
Privacy: Avoid logging user coordinates or identifiable place lookups to persistent logs unless required and consented.

For the latest implementation details, endpoint names, and example clients, see the source and README in the repository: https://github.com/foursquare/foursquare-places-mcp.

Foursquare Places MCP Server for Global Recommendations