Claude Media
Upstash MCPサーバーでRedis・QStash・Workflowを操作する
Claude CodeMCPClaude連携チュートリアル

Upstash MCPサーバーでRedis・QStash・Workflowを操作する

Upstashが公開する2種類のMCPサーバー(アカウント管理・データ操作)と、公式Redis MCPとの違いをまとめ、それぞれの接続手順を扱います。

読了目安 約16分

Upstashは性格の違う2種類のMCPサーバーを公開しています。ひとつはアカウント全体を扱う@upstash/mcp-serverです。Redisデータベースの作成やバックアップ管理、QStashのログ確認、Workflowの実行状況の追跡、さらにUpstash Boxというリモートコンテナの操作まで担います。もうひとつは@upstash/redis-mcpで、すでに存在するRedisデータベースへコマンドを投げるだけの軽量な2ツール構成です。名前が似ているredis/mcp-redisはUpstash製ではなく、Redis社が公開する汎用のRedis MCPサーバーです。

どのサーバーを入れるか

迷ったときは、操作したい範囲で決まります。

選び方

3つのRedis系MCPサーバー

  • @upstash/mcp-server

    Upstashアカウント全体が対象です。DBの作成やバックアップ管理、QStashとWorkflowのログ閲覧、Boxの操作まで担います。メールアドレスとAPIキーで認証します。

  • @upstash/redis-mcp

    既存のUpstash Redisへコマンドを実行するだけの構成です。REST URLとトークンで接続し、ツールは2つです。

  • redis/mcp-redis

    Redis社の汎用サーバーで、Upstash以外のRedisも対象です。Pythonパッケージで、uvxで起動します。

redis/mcp-redisはUpstash固有のREST URLとトークンを使いません。REDIS_HOST・REDIS_PORT・REDIS_PWDといった通常のTCP接続情報か、--url redis://…の形式で接続先を渡します。Upstashのデータベースだけを扱うなら、Upstash公式の2つのどちらかで足ります。READMEによると、Redis社のサーバーが対応するトランスポートはstdioのみです。

Redis社のサーバーは、既定のユーザー名がdefault、既定のホストが127.0.0.1、ポートが6379です。書き込みを防ぎたいときは、Redis側のACLで読み取り専用ユーザーを作る方法がREADMEに載っています。

ACL SETUSER readonlyuser on >mypassword ~* +@read -@write

認証情報はどこに保存されるか

claude mcp addのスコープによって、APIキーが書き込まれる場所が変わります。v2.1.289でのスコープ別の保存先は次のとおりです。

くらべる

スコープ別の保存先(v2.1.289)

ユーザー側の設定ファイル

既定(local)

環境変数は、ホームディレクトリの~/.claude.jsonにプロジェクトごとのエントリとして保存されます。作業ディレクトリにはファイルが作られないため、Gitに入る心配がありません。

プロジェクトの.mcp.json

--scope project

作業ディレクトリに.mcp.jsonが作られ、--api-keyの値がargsにそのまま入ります。コミットするとAPIキーがリポジトリに残ります。

既定スコープで@upstash/redis-mcpを追加したときの保存内容は、次のとおりです。

claude mcp add upstash-redis \
  -e UPSTASH_REDIS_REST_URL=https://example.upstash.io \
  -e UPSTASH_REDIS_REST_TOKEN=dummy \
  -- npx -y @upstash/redis-mcp
Added stdio MCP server upstash-redis with command: npx -y @upstash/redis-mcp to local config

~/.claude.jsonの該当エントリには、"type": "stdio"、"command": "npx"、"args": ["-y", "@upstash/redis-mcp"]と、envに渡した2つの値が入ります。一方、--scope projectで@upstash/mcp-serverを追加すると、.mcp.jsonのargsに--emailと--api-keyの値が平文で並びます。チームで共有する設定にしたい場合は、メールとAPIキーを直接書かない運用が要ります。権限設計の全般はMCPセキュリティガイドにまとめています。

アカウント管理サーバーをセットアップする

@upstash/mcp-serverはUpstashのメールアドレスとAPIキーで認証します。APIキーはUpstash Console → Account → API Keysから発行します。

claude mcp add --scope user upstash -- npx -y @upstash/mcp-server@latest \
  --email YOUR_EMAIL --api-key YOUR_API_KEY

claude mcp addの共通オプションはClaude Code MCP設定ガイドで扱っています。

読み取り専用のAPIキーで起動すると、データベース作成・バックアップ削除・Workflowの再試行のような書き込み系ツールは自動的に無効化されます。Redisへの問い合わせ、QStashのログとスケジュール確認、Workflowログの閲覧といった読み取り系はそのまま使えます。ただしUpstash Boxのツールは、読み取り専用キーではそもそも利用できません。

アカウントを持たずにRedisを試したいだけなら、redis_database_start_freeツール(またはエンドポイントhttps://upstash.com/start-redisへの直接POST)でサインアップ不要の無料データベースを起動できます。72時間で失効しますが、Upstashアカウントで引き取ればそのまま使い続けられます。ツールにuser_agentを渡すと、User-Agentヘッダーとして転送されます。エンドポイントを直接叩くときは、同じヘッダーに加えてUUIDv4のIdempotency-Keyを付ける仕様です。

QStashのログ調査とWorkflowの再実行

アカウント管理サーバーがあると、QStashの障害調査やWorkflowの再実行を会話ベースで進められます。READMEに載っている指示例は次のとおりです。

QStashのログを確認して、Webhookが失敗し続けている原因を教えて
今日失敗したWorkflow実行を@adminユーザー分だけ探して
2時間前に開始して失敗したWorkflow実行をリトライして

DLQ(デッドレターキュー)の中身をエラー種別ごとにまとめさせたり、エラーが出ているスケジュールを一時停止させたりする例もあります。管理画面を都度開かずに、原因調査からリトライの判断までをエージェント側に任せられるのが、データ操作専用サーバーには無い部分です。Redis自体の管理にも同じ書き方が使えます。

  • 「us-east-1に新しいRedisデータベースを作って」
  • 「メモリ使用量順にデータベース一覧を見せて」
  • 「このDBのバックアップを取ってからクリアして」
  • 「過去7日間のスループットの急増を見せて」

Upstash Boxをワークスペースとして使う

Upstash Boxは、独自のファイルシステムを持つリモートのLinuxコンテナです。エージェント本体は手元のマシンで動き続け、ファイル操作はbox_read/box_write/box_edit、コマンド実行はbox_exec、Gitとコード検索はbox_git、起動中サーバーの確認はbox_previewが担当します。

Boxを使うにはUpstashアカウントのAPIキーとは別のBox専用APIキーが必要です。READMEの冒頭にあるインストールコマンドにはBoxキーが含まれていないため、渡し忘れると最初のBox呼び出しが失敗します。

手順

Boxを使い始める手順

  1. 1

    Box APIキーを渡して登録する

    --box-api-keyフラグかUPSTASH_BOX_API_KEY環境変数で渡します。Boxだけ使うなら、アカウント資格情報なしで--box-api-keyだけでも起動できますが、その場合Redis・QStash・Workflowのツールは使えません。

  2. 2

    Boxを作って使い回す

    作成は、コンテナが立ち上がりきる前に応答が返る非同期の処理です。clone_repoはBoxがidle状態になってからクローンを始めるので、最初の読み取りは少し間を置いて行います。作成したBoxのIDは使い回します。

  3. 3

    ローカルの未コミット変更は別途コピーする

    クローンで入るのはpush済みの内容だけです。手元の未コミットの変更を持ち込むにはbox_uploadを使います。

claude mcp add --scope user upstash -- npx -y @upstash/mcp-server@latest \
  --email YOUR_EMAIL --api-key YOUR_API_KEY --box-api-key YOUR_BOX_API_KEY

READMEには次のような指示例があります。

  • 「このリポジトリをクローンしてBoxを立ち上げ、テストを実行して」
  • 「このBoxをスナップショットして、5つコピーを作り、それぞれにGitHub issueを割り当てて」
  • 「Boxが起動に失敗し続ける。ログを見て原因を教えて」

ローカルの標準ツールはBoxに効かない

一番の落とし穴は、Claude Codeの標準ツール(Read・Write・Edit・Bash・Glob・Grep)がBoxではなく、手元のマシンに作用することです。ローカルのファイルを読んでBoxへ書いたつもりが、実際にはローカル側を編集していた、という取り違えが起きます。README自身が、どちらのマシンにも不整合が報告されないと書いています。

くらべる

どのツールがどのマシンに効くか

リモートのコンテナ

Boxのツール

box_read・box_write・box_edit・box_exec・box_git・box_previewは、Box内のファイルとプロセスに作用します。

手元のマシン

標準ツール

Read・Write・Edit・Bash・Glob・Grepはこちらです。box_uploadだけは例外で、MCPサーバーが動くマシンのパスを意図的に読み、Boxへコピーします。

READMEによると、サーバーは起動時に案内文を送り、各Boxツールも対象マシンを示します。それでも境界を強制したい場合は、プロジェクトのCLAUDE.mdに作業場所を明記する方法が示されています。

# Workspace
The workspace for this project is an Upstash Box, not this directory.
- Use `box_read`, `box_write` and `box_edit` for files; `box_exec` for commands;
  `box_git` for git and for search (`git grep`, `git ls-files`).
- Do not use Read, Write, Edit, Bash, Glob or Grep for project files.
- The one exception is `box_upload`.
- The box id for this project is: <paste it here>

標準のstdio構成ならbox_uploadが読むのは自分のマシンのパスです。--transport httpでサーバーをリモートに置いた場合は、サーバーが動くホストのファイルシステムを読みます。

データ操作専用サーバー(@upstash/redis-mcp)を使う

すでにあるUpstash Redisへのコマンド実行だけなら、@upstash/redis-mcpのほうが軽量です。設定はすべて環境変数とCLIフラグで行い、設定ファイルはありません。ツールは2つです。

  • redis_run_commands: GET・SET・SCAN・ZADD・EVALやSEARCH.*系を含む任意のRedisコマンドを実行する
  • redis_search_docs: Upstash Redisのドキュメントを検索する。裏側はContext7の無料枠で、APIキー不要

接続方式は2通りで、HTTP(REST)ならUPSTASH_REDIS_REST_URLとUPSTASH_REDIS_REST_TOKEN、TCPならUPSTASH_REDIS_TCP_URL(またはREDIS_URL)を使います。

redis_run_commandsは複数コマンドを配列で渡すと既定でパイプライン実行になり、1つが失敗しても他のコマンドの結果には影響しません。MULTI/EXECのような原子性が必要ならtransaction: trueを指定します。

{
  "commands": [["SET", "visits", 0], ["INCR", "visits"], ["GET", "visits"]],
  "transaction": false
}

複数のデータベースを1つのサーバーで扱いたい場合は、環境変数名に任意の名前を挟むか(UPSTASH_REDIS_PROD_REST_URLのように)、CLIで--databaseを繰り返すことで名前付きデータベースを登録できます。呼び出し時はdatabaseパラメータで選びます。--readonlyフラグは書き込みコマンドをベストエフォートで拒否します。確実に防ぎたいなら、読み取り専用のREST側トークンを発行するほうが堅牢です。

接続先がHTTP/RESTかTCPかは、対象データベースの設定によって自動的に決まり、エージェント側が選ぶ余地はありません。呼び出しごとにrest_url/rest_token(HTTP)やconnection_string(TCP)を渡して登録済みの設定を上書きすることもできますが、この値はモデルのコンテキストを経由します。機密情報を扱う場面では、環境変数やCLIフラグで固定しておくほうが安全です。

--transport httpで起動すると、エンドポイントは/mcp、ヘルスチェックは/pingになります。--debugを付けると、標準エラー出力に加えてredis-mcp-debug.logにも詳細ログが残ります。

よくあるつまずき

  • 最初のBox呼び出しが失敗する: Box専用キーが渡っていない状態です。--box-api-keyかUPSTASH_BOX_API_KEYを渡して登録し直す
  • 読み取り専用キーでBoxのツールが使えない: キーの種類による仕様で、Boxを使うなら読み取り専用でないキーが要る
  • Telemetryが気になる: @upstash/mcp-serverはSDKバージョン、ランタイム情報、OSとアーキテクチャなどの匿名診断情報を送る。アカウントデータ・ツールの引数・実行結果は集めないとされ、止めたいなら--disable-telemetryを付ける。@upstash/redis-mcpはHTTPリクエストにUpstash-Telemetry-*ヘッダーを付け、--disable-telemetryかUPSTASH_DISABLE_TELEMETRY=trueで止まる
  • サーバーの動作がおかしい: @upstash/mcp-serverは--debugを付けると内部イベントが標準エラー出力に書かれ、MCPクライアントのログ表示から見られる
  • redis/mcp-redisと混同して環境変数を間違える: Upstash公式の2サーバーはUPSTASH_REDIS_REST_URL/REST_TOKEN、Redis社のサーバーはREDIS_HOST/REDIS_PORT/REDIS_PWDと、設定項目の形式自体が違う

まとめ

日常の作業はUpstash SkillとCLIが推奨されているため、@upstash/mcp-serverを入れる場面は、Boxを使うときと、QStashやWorkflowのログ調査を会話で進めたいときに絞られます。Redisのコマンド実行だけなら、軽量な@upstash/redis-mcpで足ります。調べるだけの用途なら、読み取り専用のAPIキーで起動し、--scope projectで共有する設定にはキーを書かない構成から始める選択肢があります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →