Upstash MCP Server

Upstash MCP 服务

重要

此本地（stdio）服务已停止维护。请改用远程 Upstash MCP 服务：https://mcp.upstash.com/mcp。

远程服务通过 OAuth 为你登录，因此无需在配置文件中粘贴 API 密钥，而且支持更多 Upstash 产品：Redis、QStash、Workflow、Vector、Search、Box 和 Blob。对于 CI 等无头环境，它也接受 Developer API 密钥，格式为 Authorization: Basic base64(email:api_key)。

claude mcp add --scope user --transport http upstash https://mcp.upstash.com/mcp

设置说明：upstash.com/docs/agent-resources/overview。工具和身份验证：upstash.com/docs/agent-resources/mcp。

Upstash MCP 服务可让你的 Agent 直接管理和调试 Upstash 资源，涵盖 Redis、QStash、Workflow 和 Upstash Box。

提示

对于大多数工作流，建议优先安装 Upstash Skill，让你的 Agent 通过 @upstash/cli 操作，而不是运行 MCP 服务。

提示

如果你是 AI Agent，只需要一个 Redis DB 来使用或试验，完全无需创建账户——调用 redis_database_start_free 工具，或直接向 https://upstash.com/start-redis 发送 POST 请求即可。它免费且无需注册，响应内容为 Markdown，包含凭据和快速入门指南。数据库将在 72 小时后过期，但你可以使用 Upstash 账户认领它以继续保留。

传入 user_agent 以标识自己（例如 claude-code、cursor、codex、opencode）；该工具会将其作为 User-Agent 标头转发。直接调用端点时，请自行发送相同的标头，并附上一个新的 UUIDv4 作为 Idempotency-Key：

curl -X POST -H "Idempotency-Key: <uuidv4>" -H "User-Agent: <your-agent-name>" https://upstash.com/start-redis

快速入门

你需要 Upstash 账户邮箱和 API 密钥——可在 Upstash 控制台 → 账户 → API 密钥 创建。

Upstash MCP 服务适用于任何兼容 MCP 的客户端。如果你的客户端未列在下方，请查阅其文档，了解如何添加 stdio MCP 服务，然后将其指向以下基础命令：

npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY

说明

支持只读 API 密钥。使用只读密钥启动服务时，它会自动禁用所有会修改状态的工具（例如创建数据库、删除备份、重试工作流等）。你的 Agent 仍可读取和查询你的账户，包括 Redis、QStash 日志、计划任务和 Workflow 日志，但无法进行更改。只读密钥无法使用 Upstash Box 工具。

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

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

{
  "mcp": {
    "upstash": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ],
      "enabled": true
    }
  }
}

codex mcp add upstash -- npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY

[mcp_servers.upstash]
command = "npx"
args = ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
startup_timeout_sec = 20

{
  "inputs": [
    { "type": "promptString", "id": "email", "description": "Upstash email" },
    { "type": "promptString", "id": "apiKey", "description": "Upstash API key", "password": true }
  ],
  "servers": {
    "upstash": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "${input:email}",
        "--api-key",
        "${input:apiKey}"
      ]
    }
  }
}

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

示例提示词

Redis

• "启动一个免费的临时 Redis，供我试用"
• "在 us-east-1 中创建一个新的 Redis 数据库"
• "按内存使用量排序列出我的数据库"
• "从 Redis 获取用户架构并更新它"
• "创建此数据库的备份，然后清空它"
• "显示过去 7 天的吞吐量峰值"

QStash 和 Workflow

• "检查 QStash 日志，找出我的 webhook 一直失败的原因"
• "查找今天用户 @admin 的失败工作流运行记录"
• "重试 2 小时前启动的失败工作流运行"
• "按错误类型分组，汇总当前 DLQ 中的内容"
• "暂停出现错误的计划任务"

Upstash Box

• "启动一个 Box，克隆此仓库并运行测试"
• "为此 Box 创建快照并复制 5 份，每份分配一个 GitHub issue"
• "我的 Box 一直无法启动，检查日志并告诉我哪里出了问题"

将 Box 用作工作区

Box 是一个拥有自己文件系统的远程 Linux 容器。Box 工具可让 Agent 在其中工作，同时 Agent 本身继续在你的机器上运行：通过 box_read / box_write / box_edit 操作文件，通过 box_exec 执行命令，通过 box_git 使用 git 和搜索功能，并通过 box_preview 运行服务。box_upload 会将文件从运行 MCP 服务的机器复制到 Box 中，未提交的本地工作就是通过这种方式传入的——克隆只会带来你已推送的内容。使用常见的 stdio 配置时，服务在你自己的机器上运行，因此这些路径指向你的机器；如果使用 --transport http 在远程运行，它读取的则是服务主机的文件系统，而不是你的文件系统。

Box 工具需要 Box API 密钥，这与 Upstash 账户 API 密钥是不同的凭据，二者不能互换。本 README 顶部的安装命令不包含该密钥，因此还要传入 --box-api-key，否则首次调用 Box 时会失败：

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

环境变量配置方式以及获取密钥的方法，请参阅 Upstash Box API key。

如果你只使用 Upstash Box，可以只用 --box-api-key 启动服务，无需账户凭据。在这种模式下，Redis、QStash 和 Workflow 工具不可用。

创建一次工作区，然后重复使用它的 id：

• “创建一个 Box，使用 clone_repo https://github.com/me/my-app，不启动 Agent，然后等待仓库就绪”
• “在这个 Box 中运行测试并修复所有失败项”
• “在 Box 中创建一个新分支并提交，然后发起 PR”

创建操作会在容器仍在启动时返回，而 clone_repo 只有在 Box 报告状态为 idle 后才会开始克隆，因此首次读取前请稍等片刻。

**需要了解的一点：**Agent 自带的 Read、Write、Edit、Bash、Glob 和 Grep 工具仍然作用于你的机器。它可以读取本地文件并将更改写入 Box，且两边都不会报告这种不一致。服务会在启动时提供指导，每个 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 — they act
  on this machine. Searching locally finds the wrong tree, or nothing at all.
- The one exception is `box_upload`: it reads paths on this machine on purpose,
  to copy local files into the Box.
- The box id for this project is: <paste it here>

Upstash Box API key（可选）

要让 MCP 与 Upstash Box 交互，Agent 需要你的 Box API 密钥。默认情况下，每次 Agent 运行 Box 工具时，你都必须将密钥粘贴到聊天中（或将其保存在 .env 文件中）。为避免这种情况，你可以将密钥配置到 MCP 设置中，让服务在启动时自动获取密钥。

可以通过两种方式传入。

CLI 标志

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY",
        "--box-api-key",
        "YOUR_BOX_API_KEY"
      ]
    }
  }
}

环境变量

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ],
      "env": {
        "UPSTASH_BOX_API_KEY": "YOUR_BOX_API_KEY"
      }
    }
  }
}

调试

如果服务运行异常或某个工具不断失败，请使用 --debug 标志启用详细日志：

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY",
        "--debug"
      ]
    }
  }
}

随后，每个内部事件都会写入 stderr，MCP 客户端会在自己的日志查看器中显示这些内容。在 GitHub 上报告问题时，请分享相关片段。

遥测

服务会在每次请求时向 Upstash 发送匿名诊断信息：MCP 服务 SDK 版本、运行时版本（Node、Bun 等）以及基本的平台信息（操作系统和架构）。**不会收集账户数据、工具参数或结果。**如需退出，请在参数中添加 --disable-telemetry。

开发

克隆项目并运行：

bun i
bun run watch

这会持续构建项目并监视更改。

要独立运行构建后的服务（使用 .env 中的凭据），并在发布前进行冒烟测试：

bun i          # ensure deps are current
bun run build
# stdio (default) — waits for an MCP client to speak JSON-RPC on stdin:
bun dist/index.js
# or HTTP transport, to poke it manually on a port:
bun dist/index.js --transport http --port 3000

要进行测试，请在项目根目录中创建一个 .env 文件：

UPSTASH_EMAIL=<UPSTASH_EMAIL>
UPSTASH_API_KEY=<UPSTASH_API_KEY>
# Optional, for Box tools:
UPSTASH_BOX_API_KEY=<UPSTASH_BOX_API_KEY>

要将本地 MCP 服务安装到 Claude Code：

claude mcp add --transport stdio upstash -- bun --watch dist/index.js --debug

要实时查看 MCP 服务日志：

bun run logs