Hoppscotch MCP Server

A Model Context Protocol (MCP) server that enables AI agents like Claude to interact with Hoppscotch: managing collections, environments, teams, and API workflows programmatically.

Features

• 53 MCP tools for comprehensive API workflow management
• Collection management: create, update, delete, import/export, duplicate, and move collections. The one search tool, search_team_requests, searches a team's requests by title, not collections
• Environment management: manage environment variables across deployment stages
• Team collaboration: full team workspace support including member management
• Request execution: execute HTTP requests with authentication and environment variable substitution
• Response validation: validate API responses against expected criteria (status, headers, body, response time)
• Code generation: generate code snippets in curl, JavaScript, Python, Go, and Rust
• Documentation generation: auto-generate API documentation in Markdown
• REST and GraphQL collections: personal collections and requests carry a REST/GraphQL type; team collections are untyped
• Cloud and self-hosted targeting: Cloud (hoppscotch.io) is supported. Self-hosted instances use <server URL>/backend by default. Set HOPPSCOTCH_API_URL for a different backend URL. See Cloud / self-hosted compatibility for the verification boundary
• Browser-based login: no token setup required for interactive use. Sign in through Hoppscotch's device-login page and the session is cached

Installation

Via npx (recommended, no install needed)

npx @hoppscotch/mcp-server

From npm

npm install -g @hoppscotch/mcp-server

This also installs the hoppscotch-mcp binary, which the client configs below can use in place of npx.

From source

This project uses pnpm (corepack enable picks up the pinned version):

git clone https://github.com/hoppscotch/hoppscotch-mcp-server.git
cd hoppscotch-mcp-server
pnpm install
pnpm run build

Released builds carry the Firebase Web API key needed for Cloud sign-in; a build from source does not. To use Cloud from a source build, provide HOPPSCOTCH_FIREBASE_API_KEY either at build time (it gets baked into the bundle) or at runtime in your MCP client's env block. The runtime value takes precedence, so no rebuild is needed. Without it, Cloud sign-in fails with a clear error. Self-hosted instances don't use Firebase and need nothing extra.

Quick Start

1. Configure your MCP client

Claude Code / Codex: register the server once at user scope. For a self-hosted instance, pass HOPPSCOTCH_SERVER_URL through the host's env flag (-e for Claude Code, --env for Codex). If the backend is not available at <server URL>/backend, also set HOPPSCOTCH_API_URL to the backend API base URL.

claude mcp add -s user hoppscotch -- npx -y @hoppscotch/mcp-server
codex mcp add hoppscotch -- npx -y @hoppscotch/mcp-server

Claude Desktop: edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hoppscotch": {
      "command": "npx",
      "args": ["-y", "@hoppscotch/mcp-server"]
    }
  }
}

For a self-hosted instance:

{
  "mcpServers": {
    "hoppscotch": {
      "command": "npx",
      "args": ["-y", "@hoppscotch/mcp-server"],
      "env": {
        "HOPPSCOTCH_SERVER_URL": "https://your-hoppscotch.example.com"
      }
    }
  }
}

For a self-hosted instance with a separate backend URL:

{
  "mcpServers": {
    "hoppscotch": {
      "command": "npx",
      "args": ["-y", "@hoppscotch/mcp-server"],
      "env": {
        "HOPPSCOTCH_SERVER_URL": "https://your-hoppscotch.example.com",
        "HOPPSCOTCH_API_URL": "https://api.your-hoppscotch.example.com"
      }
    }
  }
}

2. Authenticate

On the first tool call the server opens hoppscotch.io/device-login (or your self-hosted equivalent) in your browser. Sign in and the session is saved automatically, so subsequent calls skip the browser step.

Note: Cloud sessions are refreshed automatically through the stored Firebase refresh token and may occasionally re-prompt for login. Sessions against the current Community Edition are not refreshed by this release (its refresh endpoint is cookie-based and this server does not use it; Enterprise/custom backends were not verified either way), so a new browser sign-in is needed when the token expires (backend-configured; the Community Edition default is one day). The sign-in page is the one the Hoppscotch Desktop app uses, so its copy says "Desktop".

Configuration

Most setups need none of these. The Quick Start above sets no environment variables at all: Cloud is the default and the browser login flow handles auth. Everything below is optional, and each variable exists to serve one specific situation.

Commonly set

| Variable | Default | Purpose | |---|---|---| | HOPPSCOTCH_SERVER_URL | https://hoppscotch.io | Frontend URL. Omit for Cloud; set to your instance URL for self-hosted. The device-login page opens from this URL. | | HOPPSCOTCH_API_URL | derived from HOPPSCOTCH_SERVER_URL | Overrides the backend API base URL. Include any base path, without /graphql. | | HOPPSCOTCH_TOOL_PROFILE | core | Tool surface: minimal (22), core (default, 39), standard (38), or full (53). core covers CRUD + request execution + codegen + read-only team discovery; standard swaps in team administration + advanced collection ops; full is everything. core and standard are separate branches of full, not a ladder. An unknown value falls back to core with a stderr warning. | | HOPPSCOTCH_DEFAULT_TEAM_ID | — | Default team ID for team-scoped tools when omitted from the call. |

Headless and non-interactive use

| Variable | Default | Purpose | |---|---|---| | HOPPSCOTCH_ACCESS_TOKEN | — | A Hoppscotch JWT to skip browser login (e.g. for headless/CI). A pat-… PAT does not work (REST-only). | | HOPPSCOTCH_FORCE_BROWSER_LOGIN | false | Set true to attempt browser login even when a headless environment is detected. | | HOPPSCOTCH_AUTH_TIMEOUT_MS | 60000 | How long a tool call waits for browser sign-in before returning retry guidance (with the login URL once it is available). The local callback stays open ~5 min regardless, so a slower sign-in still completes. |

Request execution

| Variable | Default | Purpose | |---|---|---| | HOPPSCOTCH_TIMEOUT | 30000 | Request timeout (ms). | | HOPPSCOTCH_MAX_RESPONSE_BYTES | 5000000 | Cap on the response body execute_request buffers; a body that would exceed it is cut off and flagged truncated. Two limits apply: the raw read stops at the cap plus a small internal redaction margin (bytes), and the returned redacted text is additionally capped at the same number of UTF-16 code units — byte-exact for ASCII bodies; a non-ASCII body can be cut below the byte figure by the raw read, or come back somewhat larger than it after redaction. (Raw bytes that only spill into the internal redaction margin but shrink back under the cap after redaction are complete, not flagged.) | | HOPPSCOTCH_ALLOW_PRIVATE_HOSTS | false | Set true to disable SSRF protection so execute_request can reach loopback/private/self-hosted targets. Only on trusted input. |

Hardening (opt-in)

Both default to off, so behaviour is unchanged unless you set them.

| Variable | Default | Purpose | |---|---|---| | HOPPSCOTCH_SECRET_ALLOWED_ORIGINS | — | Comma-separated origins (e.g. https://api.example.com) allowed to receive secret environment values via {{var}} substitution in execute_request/validate_response. Unset ⇒ no restriction (secrets substitute freely). Set it to opt in: only the listed origins may then receive secrets; a secret referenced in a request to any other origin is refused. | | HOPPSCOTCH_STRICT_ENV | false | Set true to harden against a hostile working-directory .env: trust-sensitive vars (auth target/token, tool profile, SSRF/secret-egress toggles, default team) that a .env introduces are then ignored and must come from the real environment. Off by default; a .env is honoured in full. |

Building from source

| Variable | Default | Purpose | |---|---|---| | HOPPSCOTCH_FIREBASE_API_KEY | baked in at build | Firebase Web API key used for Hoppscotch Cloud sign-in. Released builds have it baked in, so you normally never set this. Set it when building from source and using Cloud: a source build without it fails Cloud sign-in with a clear error. Not used by self-hosted instances. |

Hardening a .env-loading setup. By default a working-directory .env is honoured for every variable (backwards-compatible). If you run this server in an editor that may open untrusted repositories, set HOPPSCOTCH_STRICT_ENV=true in your MCP client's env block so a hostile repo .env can't repoint the auth target, disable the SSRF guard, or allowlist a secret-exfiltration origin.

For Hoppscotch Cloud, leave both URL variables unset and sign in normally. For self-hosted instances, set HOPPSCOTCH_SERVER_URL to the frontend URL. Set HOPPSCOTCH_API_URL when the backend is not available at <server URL>/backend. This override does not change device login or auth mode.

Authentication

The server uses a browser-based device login flow, driven by Hoppscotch's /device-login page:

1. On first tool call, a temporary local HTTP server starts on a random port.
2. Your browser opens <HOPPSCOTCH_SERVER_URL>/device-login?redirect_uri=http://localhost:<port>/callback/<nonce>.
3. After sign-in, the server receives your tokens via the callback.
4. Tokens are stored at ~/.config/hoppscotch-mcp/auth.json (permissions: 600).
5. Cloud tokens (Firebase-backed, ~1 hour) are refreshed automatically before expiry via the stored Firebase refresh token; a new browser login is needed only if a refresh fails. Tokens from the current Community Edition are not refreshed in this release: when the JWT expires (backend-configured; the CE default is one day), the next tool call opens a new browser sign-in. Enterprise/custom backends were not verified either way.

Advanced: override token. You can set HOPPSCOTCH_ACCESS_TOKEN to a valid JWT (e.g. copied from ~/.config/hoppscotch-mcp/auth.json after a device login) to skip the browser flow. Note that Hoppscotch PATs (pat-xxx) only work with REST API endpoints, not GQL queries, so they will not work here.

Non-interactive / headless (CI, containers, SSH)

There is no browser on these hosts, so the device-login flow can't run. The server detects headless environments (CI / SSH / no display) and fails fast with guidance instead of hanging. To run non-interactively:

1. On a machine with a browser, complete a device login once.
2. Copy the accessToken JWT from ~/.config/hoppscotch-mcp/auth.json.
3. Set HOPPSCOTCH_ACCESS_TOKEN=<that JWT> in the headless environment.

If you genuinely have a browser available but detection misfires, set HOPPSCOTCH_FORCE_BROWSER_LOGIN=true.

Known limitations (current release)

• execute_request is a real HTTP client. By default it blocks requests to loopback, link-local, cloud-metadata (169.254.169.254), and private-network addresses (SSRF protection), covering IPv4/IPv6 and additional special-use ranges. The validated address is pinned at connect time (via an undici dispatcher), so a same-host DNS-rebinding race between check a