swarm-mcp

An MCP server over a Foursquare Swarm check-in history, back to the first check-in.

Status

Shipped — the oldest project on the list, first committed December 2025.

License

MIT

Features

Tool Description
get_checkins Get paginated check-in history
get_checkins_by_date_range Get check-ins within a specific date range
get_recent_checkins Get check-ins from the past X days
get_checkin_details Get details about a specific check-in
get_venue_details Get venue info: ratings, hours, tips, photos
get_all_checkins Retrieve your entire check-in history
get_checkin_stats Get statistics (total count, date range, averages)
get_categories List all unique categories in your history with counts
get_top_venues Get your most visited venues with filters
search_checkins Search with filters: query, category, city, state, country, date range
get_server_info Get server metadata, data sources, and tool costs

All responses include a _meta block with transparency info (completeness, API calls made, data scope) to help AI models make informed decisions about expensive operations.

Tool Costs

Tool Cost Notes
get_checkins Low Single paginated request
get_checkins_by_date_range Low Single request with date filters
get_recent_checkins Low Single request with time filter
get_checkin_details Low Single check-in lookup
get_venue_details Low Single venue lookup
get_checkin_stats Low 2 API calls (newest + oldest)
get_categories High Scans history to discover unique categories
get_top_venues High Scans history to aggregate venue visits
get_server_info None Local introspection only
get_all_checkins High 1 API call per 250 check-ins
search_checkins High Client-side filtering; scans up to 5000 items

Example _meta Response

Every tool response includes metadata like this:

{
  "_meta": {
    "is_complete": true,
    "returned_count": 50,
    "total_available": 1847,
    "limit_applied": 50,
    "api_calls_made": 1,
    "data_source": "foursquare_swarm_api",
    "data_scope": "authenticated_user_checkins"
  },
  "checkins": [...]
}

Installation

uvx swarm-mcp

Using pip

pip install swarm-mcp

Setup

1. Get Your Foursquare Access Token

You’ll need a Foursquare OAuth2 access token:

  1. Go to Foursquare Developer Apps
  2. Create a new app (or use an existing one)
  3. Note your Client ID and Client Secret
  4. Generate an access token using the OAuth2 flow, or use the API Explorer to get a token quickly

Security: Treat FOURSQUARE_TOKEN like a password—don’t commit it, paste it in issues, or share screenshots with it visible.

2. Configure Your MCP Client

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "swarm": {
      "command": "uvx",
      "args": ["swarm-mcp"],
      "env": {
        "FOURSQUARE_TOKEN": "your-access-token-here"
      }
    }
  }
}

Claude Code

claude mcp add swarm uvx swarm-mcp -e FOURSQUARE_TOKEN=your-access-token-here

Or add manually to your config:

{
  "Swarm": {
    "command": "uvx",
    "args": ["swarm-mcp"],
    "env": {
      "FOURSQUARE_TOKEN": "your-access-token-here"
    }
  }
}

Usage Examples

Once configured, you can ask Claude things like:

Example Output

📊 SWARM CHECK-IN STATS
=============================================
Total check-ins:      12,456
Years active:         10.2 years
Days active:          3,726
Avg check-ins/day:    3.34

📅 First check-in: March 15, 2014 at Coffee Shop (NYC)
📍 Most recent: Today at Office (San Francisco)

Development

# Clone the repo
git clone https://github.com/alexpriest/swarm-mcp.git
cd swarm-mcp

# Install in development mode
pip install -e .

# Run the server
FOURSQUARE_TOKEN=your-token swarm-mcp

API Reference

This server uses the Foursquare API v2:

License

MIT License - see LICENSE for details.

This site is open source. Improve this page.