swarm-mcp

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

Status

Shipped and maintained. First released December 18, 2025, ten months before Foursquare shipped its own Swarm MCP in October 2026. Re-verified against the live Foursquare API on October 27, 2026: all 11 tools pass.

License

MIT

History

The commit history and PyPI release history are the public record.

Features

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

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

Using uvx (recommended)

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:

• "Show me my recent Swarm check-ins"
• "How many times have I checked into coffee shops this year?"
• "What are my top 10 most visited coffee shops?"
• "Show me all my check-ins in California"
• "What are my check-in stats?"
• "Get details about [venue name]" (ratings, hours, tips)
• "What are the ratings for my favorite restaurants?"

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:

• User Check-ins
• Check-in Details

License

MIT License - see LICENSE for details.