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

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