Skip to main content
Glama
Foursquare MCP Server

Foursquare MCP Server

Foursquare MCP Server

An MCP server that exposes Foursquare/Swarm checkin data and user activity through 13 tools. Built with FastMCP, it supports stdio and HTTP transports.

Features

  • User management — register multiple Foursquare accounts by OAuth token

  • Checkins — fetch checkin history with date filtering and pagination, or get full detail for a single checkin

  • Venue details — look up any venue by ID

  • Venue history — unique venues visited with visit counts and timestamps

  • Mayorships — current venues where a user is mayor

  • Lists — saved, created, and followed lists with full venue details

  • Tastes — user food/experience preferences

  • Cross-user search — query checkins across all registered users at once

Related MCP server: Dawarich MCP

Requirements

  • Python 3.11+

  • uv (recommended) or pip

Setup

1. Install

cd foursquare_mcp
uv sync

Or with pip:

pip install -e .

2. Get a Foursquare OAuth Token

Option A — Interactive OAuth flow:

Create a .env file with your Foursquare app credentials (see .env.example):

FOURSQUARE_CLIENT_ID=your_client_id
FOURSQUARE_CLIENT_SECRET=your_client_secret

Then run the setup command:

foursquare-mcp setup --username alice

This opens a browser-based OAuth flow and saves the token automatically.

Option B — Manual token:

If you already have an OAuth token:

foursquare-mcp add-user --username alice --token YOUR_OAUTH_TOKEN

Tokens are stored in ~/.config/foursquare-mcp/users.json.

3. Run the Server

stdio (default, for local MCP clients):

foursquare-mcp serve

HTTP (for remote or shared access):

foursquare-mcp serve --transport streamable-http --host 0.0.0.0 --port 8006

MCP Client Configuration

Add to your MCP client config (e.g. .mcp.json):

stdio:

{
  "mcpServers": {
    "foursquare": {
      "command": "foursquare-mcp",
      "args": ["serve"]
    }
  }
}

Streamable HTTP:

{
  "mcpServers": {
    "foursquare": {
      "type": "streamable-http",
      "url": "http://localhost:8006/mcp"
    }
  }
}

Tools

User Management

Tool

Description

list_users

List all registered Foursquare usernames

add_user

Register a user's OAuth token

remove_user

Remove a registered user

get_user_details

Get a user's Foursquare profile

Checkins

Tool

Description

get_user_checkins

Get checkins with optional date range and limit

get_checkin_detail

Get full detail for a single checkin (comments, photos, overlaps)

search_all_users_checkins

Search checkins across all registered users

Venues

Tool

Description

get_venue_details

Get full venue info by venue ID

get_user_venue_history

Get unique venues visited with visit counts and timestamps

Social

Tool

Description

get_user_mayorships

Get venues where the user is currently mayor

get_user_lists

Get all lists (saved, created, followed)

get_list_detail

Get full list detail with all venue items

get_user_tastes

Get taste preferences (food types, experiences)

CLI Commands

foursquare-mcp serve          Start the MCP server
foursquare-mcp setup          Authenticate via OAuth and save token
foursquare-mcp add-user       Register a token manually
foursquare-mcp remove-user    Remove a registered user
foursquare-mcp list-users     List registered users

Run foursquare-mcp --help for full option details.

Running as a systemd Service

# ~/.config/systemd/user/foursquare-mcp.service
[Unit]
Description=Foursquare MCP Server

[Service]
WorkingDirectory=/path/to/foursquare_mcp
ExecStart=/path/to/uv run foursquare-mcp serve --transport streamable-http --host 0.0.0.0 --port 8006
Restart=on-failure

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now foursquare-mcp

Available Tools

13 tools
add_userAdd UserC

Register a new user's Foursquare OAuth token.

Inputs: username (required), oauth_token (required). Returns: object

get_checkin_detailGet Checkin DetailB

Get full detail for a single checkin by ID (includes comments, photos, overlaps, etc.).

Inputs: username (required), checkin_id (required). Returns: object

get_list_detailGet List DetailA

Get full detail for a specific list including all venue items. List IDs come from get_user_lists.

Inputs: list_id (required). Returns: object

get_user_checkinsGet User CheckinsC

Get checkins for a registered user within an optional date range.

Inputs: username (required), limit, after_date, before_date. Returns: object

get_user_detailsGet User DetailsB

Get Foursquare profile for a registered user.

Inputs: username (required). Returns: object

get_user_listsGet User ListsA

Get all lists for a user (saved places, created lists, followed lists).

Inputs: username (required). Returns: object

get_user_mayorshipsGet User MayorshipsB

Get a user's current mayorships (venues where they're the mayor).

Inputs: username (required). Returns: object

get_user_tastesGet User TastesB

Get a user's taste preferences (food types, experiences they enjoy).

Inputs: username (required). Returns: object

get_user_venue_historyGet User Venue HistoryA

Get unique venues a user has visited, with visit counts and last-visit timestamps.

Inputs: username (required), limit, after_date, before_date. Returns: object

get_venue_detailsGet Venue DetailsA

Get full venue details (address, categories, URL, etc.) by venue ID.

Inputs: venue_id (required). Returns: object

list_usersList UsersB

List all registered Foursquare usernames.

Inputs: no named parameters. Returns: object

remove_userRemove UserC

Remove a registered user.

Inputs: username (required). Returns: object

search_all_users_checkinsSearch All Users CheckinsB

Search checkins across ALL registered users within an optional date range.

Inputs: limit, after_date, before_date. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action: user management (list/add/remove/get), checkin retrieval (per user and across all users), venue details, list details, and user-specific aggregates (venue history, mayorships, tastes). The only potential overlap is between get_user_checkins and get_user_venue_history, but the latter provides aggregated unique visit data, making the purposes distinct.

    Naming Consistency4/5

    All tools use snake_case with a consistent verb_noun pattern (list_, add_, remove_, get_, search_). However, there is a minor inconsistency in pluralization: 'get_user_details' and 'get_venue_details' use plural 'details', while 'get_checkin_detail' and 'get_list_detail' use singular 'detail'.

    Tool Count5/5

    With 13 tools, the server is well-scoped for its purpose, covering user management, checkin retrieval, venue details, lists, and user-specific data without being excessive or too thin.

    Completeness4/5

    The tool set covers core read operations for users, checkins, venues, and lists, plus user registration and deletion. However, a notable gap is the absence of venue search (e.g., searching venues by name or location), which is a common Foursquare API capability.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Search concert setlists, artists, venues, tours, and cities from setlist.fm via natural language. Provides 16 read-only tools for exploring live music data.
      20
      332 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables place search and discovery via the Foursquare Places API v3, allowing AI assistants to find venues, search near locations, look up place details, and get location context.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Provides read-only access to X (Twitter) data — posts, threads, profiles, timelines, followers, media, and trends — through twelve tools, with no login or API key required.
      12
      21 npm
      1
      MIT