MCP 服务器

Foursquare MCP Server

Enables users to authenticate with Foursquare, check auth status, and retrieve check-in history using natural language or CLI.

README

Foursquare MCP Server

Foursquare APIとの連携を提供するModel Context Protocol (MCP)サーバーです。MCPサーバーとしての動作に加え、CLIツールとしても使用できます。

必要な環境

Bun >= 1.0.0 または Node.js >= 18.0.0
Foursquare Developer アカウント
MCPクライアント（Claude Desktop等）※MCPサーバーとして使用する場合

インストール

npm からインストール

npm install -g @upamune/foursquare-mcp

bunx を使った実行（インストール不要）

bunx @upamune/foursquare-mcp

リポジトリからの実行

git clone https://github.com/upamune/foursquare-mcp.git
cd foursquare-mcp
bun install
bun run build

CLIツールとしての使用

v0.2.0から、MCPサーバーを起動せずに直接CLIコマンドとして使用できるようになりました。

コマンドラインから直接実行

# 認証（初回のみ必要）
foursquare-mcp invoke authenticate --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# 認証状態を確認
foursquare-mcp invoke check-auth-status

# チェックインを取得
foursquare-mcp invoke get-user-checkins

# オプション付きでチェックインを取得
foursquare-mcp invoke get-user-checkins --limit 10 --sort oldestfirst

# JSON形式で出力
foursquare-mcp invoke get-user-checkins --json

# 特定の日時以降のチェックインを取得
foursquare-mcp invoke get-user-checkins --after 1735689600

利用可能なCLIコマンド

`invoke authenticate`

Foursquare認証を行います。ブラウザが自動的に開き、ログイン後トークンが保存されます。

オプション:

--client-id <ID>: Foursquare CLIENT_ID
--client-secret <SECRET>: Foursquare CLIENT_SECRET

`invoke check-auth-status`

保存されたトークンの有効性を確認します。

`invoke get-user-checkins`

チェックイン履歴を取得します。

オプション:

--limit <数値>: 取得件数（デフォルト: 50）
--after <timestamp>: このUnixタイムスタンプ以降のチェックイン
--sort <順序>: newestfirst または oldestfirst
--json: JSON形式で出力

MCPサーバーとしての使用

Foursquare Developer設定

Foursquare Developer Portalでアカウントを作成
新しいアプリケーションを作成
OAuth設定でRedirect URIに http://localhost:52847/callback を追加
CLIENT_IDとCLIENT_SECRETを取得

Claude Desktop設定

~/Library/Application Support/Claude/claude_desktop_config.jsonに以下を追加：

{
  "mcpServers": {
    "foursquare": {
      "command": "bunx",
      "args": ["@upamune/foursquare-mcp"],
      "env": {
        "FOURSQUARE_CLIENT_ID": "your_client_id",
        "FOURSQUARE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

または、リポジトリをクローンした場合：

{
  "mcpServers": {
    "foursquare": {
      "command": "bun",
      "args": ["run", "/path/to/foursquare-mcp/index.ts"],
      "env": {
        "FOURSQUARE_CLIENT_ID": "your_client_id",
        "FOURSQUARE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

MCPツール一覧

authenticate

初回利用時にFoursquare認証を行います。ブラウザが自動的に開き、ログイン後トークンが保存されます。

check-auth-status

保存されたトークンの有効性を確認します。

get-user-checkins

チェックイン履歴を取得します。

パラメータ:

limit: 取得件数（デフォルト: 50、最大: 100）
afterTimestamp: 指定したUnixタイムスタンプ以降のチェックインのみ取得
sort: ソート順（"newestfirst" または "oldestfirst"）

トークン管理

トークン保存場所

Linux: ~/.config/foursquare-mcp/token.json
macOS: ~/Library/Application Support/foursquare-mcp/token.json
Windows: %APPDATA%\foursquare-mcp\token.json

環境変数でのトークン指定

FOURSQUARE_ACCESS_TOKEN 環境変数を設定することで、保存されたトークンファイルより優先してアクセストークンを使用できます：

{
  "mcpServers": {
    "foursquare": {
      "command": "bunx",
      "args": ["@upamune/foursquare-mcp"],
      "env": {
        "FOURSQUARE_CLIENT_ID": "your_client_id",
        "FOURSQUARE_CLIENT_SECRET": "your_client_secret",
        "FOURSQUARE_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}