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

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