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

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