# Foursquare MCP Server

An [MCP](https://modelcontextprotocol.io/) server that exposes Foursquare/Swarm checkin data and user activity through 13 tools. Built with [FastMCP](https://github.com/jlowin/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](https://docs.astral.sh/uv/) (recommended) or pip

## Setup

### 1. Install

```bash
cd foursquare_mcp
uv sync
```

Or with pip:

```bash
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:

```bash
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:

```bash
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):

```bash
foursquare-mcp serve
```

**HTTP** (for remote or shared access):

```bash
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:**

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

**Streamable HTTP:**

```json
{
  "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

```ini
# ~/.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
```

```bash
systemctl --user daemon-reload
systemctl --user enable --now foursquare-mcp
```