Foursquare MCP Server
Provides tools for managing Foursquare accounts and accessing checkin history, venue details, mayorships, lists, and taste preferences via the Foursquare API.
Allows retrieval of Swarm checkin data, including checkin history with date filtering, full checkin details, and cross-user search across registered accounts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Foursquare MCP Server Show my recent check-ins from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncOr 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_secretThen run the setup command:
foursquare-mcp setup --username aliceThis 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_TOKENTokens are stored in ~/.config/foursquare-mcp/users.json.
3. Run the Server
stdio (default, for local MCP clients):
foursquare-mcp serveHTTP (for remote or shared access):
foursquare-mcp serve --transport streamable-http --host 0.0.0.0 --port 8006MCP 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 all registered Foursquare usernames |
| Register a user's OAuth token |
| Remove a registered user |
| Get a user's Foursquare profile |
Checkins
Tool | Description |
| Get checkins with optional date range and limit |
| Get full detail for a single checkin (comments, photos, overlaps) |
| Search checkins across all registered users |
Venues
Tool | Description |
| Get full venue info by venue ID |
| Get unique venues visited with visit counts and timestamps |
Social
Tool | Description |
| Get venues where the user is currently mayor |
| Get all lists (saved, created, followed) |
| Get full list detail with all venue items |
| 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 usersRun 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.targetsystemctl --user daemon-reload
systemctl --user enable --now foursquare-mcpAvailable Tools
13 toolsadd_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
Scored across 13 tools
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.
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'.
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.
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
Related MCP Connectors
Search and read published GoVisit destination and local business data through 22 read-only tools.
Live X/Twitter data: profiles, tweets, search, followers, lists and trends. 29 read-only tools.
Search and read public data from X/Twitter, Reddit, YouTube, Instagram, TikTok, Facebook, Threads, Bluesky, Trustpilot, Amazon, Google Maps, news, forums and the web. 90+ read-only tools plus ready-made research playbooks (lead finding, brand monitoring, review mining). Hosted: connect with an API key; 50 free requests per endpoint each month.
Search ATProto writing, annotations, identity, agents, and forum posts. 12 read-only tools.
Related MCP Servers
- AlicenseAqualityAmaintenanceSearch concert setlists, artists, venues, tours, and cities from setlist.fm via natural language. Provides 16 read-only tools for exploring live music data.20332 npm1MIT
- FlicenseBqualityDmaintenanceEnables interaction with Dawarich location history through tools for maps, stats, places, visits, points, and trip workflows.19-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-

@xcrap/mcpofficial
AlicenseAqualityCmaintenanceProvides 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.1221 npm1MIT