Hoppscotch MCP Server

MCP server for Hoppscotch Team Collection automation.

It supports:

• Hoppscotch personal and team REST collection operations through Hoppscotch internal GraphQL.
• Safe OpenAPI sync into a dedicated generated collection or folder.
• Source-code endpoint analysis and code-based sync into Hoppscotch.
• A Generated-folder workflow that avoids modifying manual Hoppscotch folders.

Safety Model

• Sync tools default to dryRun: true.
• Write mode creates a backup under ./backups/ before mutating Hoppscotch.
• Sync matching uses stable METHOD + normalized path keys.
• Existing request scripts, auth, manual headers, and manual metadata are preserved where possible.
• Sync never deletes Hoppscotch requests automatically.
• Destructive delete tools are intentionally not exposed by this MCP server. Sync workflows never delete requests automatically. Removed endpoints are handled through deprecated markers or a Deprecated folder strategy.
• Use a dedicated Generated collection such as NMS Backend API/Generated as the sync target.
• Do not return full large exports through MCP; export tools write files and return compact metadata.

Known NMS target values:

HOPPSCOTCH_GRAPHQL_URL=https://hoppscotch.YOUR_DOMAIN/backend/graphql
Team ID=cmpcn4aya000g12lcnyif0w3w
Team name=NMS ERP
Root collection ID=cmpcn7ozh000h12lc2rtzzx2c
Root collection title=NMS Backend API
Generated collection ID=cmqi7d761003v12pbc2kdtdyj
Generated path=NMS Backend API/Generated

Installation

npm install
npm run build
npm test

Run locally:

npm start

Development mode:

npm run dev

Environment Configuration

Copy .env.example to .env and set values.

Required MCP setting:

MCP_AUTH_TOKEN=change-me

Hoppscotch settings:

HOPPSCOTCH_GRAPHQL_URL=https://hoppscotch.YOUR_DOMAIN/backend/graphql
HOPPSCOTCH_ORIGIN=https://hoppscotch.YOUR_DOMAIN
HOPPSCOTCH_COOKIE=connect.sid=...; access_token=...; refresh_token=...
HOPPSCOTCH_AUTH_UI_HOST=127.0.0.1
HOPPSCOTCH_AUTH_UI_PORT=3737
HOPPSCOTCH_AUTH_STORAGE_FILE=.hoppscotch-auth.local.json

Split cookie values are also supported and take precedence over HOPPSCOTCH_COOKIE:

HOPPSCOTCH_CONNECT_SID=...
HOPPSCOTCH_ACCESS_TOKEN=...
HOPPSCOTCH_REFRESH_TOKEN=...

Auth precedence:

• Runtime cookies updated from the Authentication Web UI.
• Local ignored auth storage file, default .hoppscotch-auth.local.json.
• HOPPSCOTCH_COOKIE.
• Split env values: HOPPSCOTCH_CONNECT_SID, HOPPSCOTCH_ACCESS_TOKEN, HOPPSCOTCH_REFRESH_TOKEN.

Authentication Web UI

hoppscotch_update_auth no longer accepts raw cookie or token values in MCP tool calls. This avoids leaking credentials into MCP logs, chat history, or tool call history.

Use the local Web UI flow:

1. In your MCP client, run hoppscotch_update_auth with { "action": "open_ui" }.
2. Open the returned URL, for example http://127.0.0.1:3737/auth?token=....
3. In browser DevTools on Hoppscotch, open Network, select a /backend/graphql request, and copy the Cookie header.
4. Paste the full Cookie header into the local UI, or paste connect.sid, access_token, and refresh_token separately.
5. Click Parse & Test to parse the cookies and run the Hoppscotch me GraphQL query without exposing cookies.
6. Click Save cookies to store normalized cookies locally.

The setup URL contains a random one-time token that expires after 10 minutes. Saving or clearing cookies invalidates the token.

Security notes:

• The auth UI binds to 127.0.0.1 by default.
• Binding to a public host requires HOPPSCOTCH_AUTH_UI_ALLOW_PUBLIC_BIND=true.
• Cookies are stored only in runtime memory and the ignored local storage file.
• .hoppscotch-auth.local.json is gitignored.
• MCP responses only include masked auth status, never raw cookie values.

Useful actions:

{ "action": "open_ui" }

{ "action": "status" }

{ "action": "clear" }

How To Copy Hoppscotch Cookies

Cookie header paste is the default supported authentication method.

1. Open Hoppscotch in your browser and log in.
2. Open DevTools → Network.
3. Click any /backend/graphql request.
4. In Request Headers, copy the full Cookie header.
5. Open the local Auth Web UI returned by hoppscotch_update_auth.
6. Paste the Cookie header into the Paste full Cookie header textarea.
7. Click Parse & Test.
8. If the test succeeds, click Save.

Supported pasted formats:

connect.sid=...; access_token=...; refresh_token=...

Cookie: connect.sid=...; access_token=...; refresh_token=...

The parser only keeps these Hoppscotch cookies:

• connect.sid
• access_token
• refresh_token

Stored cookies are normalized in this order:

connect.sid=<value>; access_token=<value>; refresh_token=<value>

Cookie values are not URL-decoded before storage. Encoded values such as %3A, %2F, and %2B are preserved exactly for outbound Cookie headers. The UI only shows masked values and local JWT metadata such as issuer, subject, issued-at, expiration, and expired status.

Hoppscotch-Like Login Feasibility

OAuth-style login through the local MCP Auth Web UI was investigated and is not implemented.

The safe default remains manual Cookie header paste because:

• Hoppscotch login and Google OAuth complete on the real Hoppscotch domain.
• Browser cookie domain rules prevent a 127.0.0.1 page from receiving cookies scoped to hoppscotch.YOUR_DOMAIN.
• Secure, SameSite, domain scoping, and server-side connect.sid session behavior are designed to prevent local pages from collecting those cookies.
• The MCP server must not read browser profile cookie databases, steal cookies, or bypass browser security.

A future safe design could open the official Hoppscotch login in the browser, let the user complete Google OAuth on the real Hoppscotch domain, then return to the local Auth UI and instruct the user to copy the Cookie header manually. Browser extensions or local helpers should only be considered with explicit approval.

OpenAPI settings:

OPENAPI_URL=http://host.docker.internal:3000/api/swagger-json
OPENAPI_BASE_URL=<<baseUrl>>
OPENAPI_AUTH_TYPE=none
OPENAPI_BASIC_AUTH_USER=
OPENAPI_BASIC_AUTH_PASSWORD=
OPENAPI_BEARER_TOKEN=
OPENAPI_CUSTOM_AUTH_HEADER_NAME=
OPENAPI_CUSTOM_AUTH_HEADER_VALUE=

Supported OPENAPI_AUTH_TYPE values:

• none
• basic
• bearer
• custom

Docker Notes

localhost inside Docker points to the MCP container, not your host machine.

If the backend runs on the host, use:

OPENAPI_URL=http://host.docker.internal:3000/api/swagger-json

On Linux, add this to Docker Compose:

extra_hosts:
  - "host.docker.internal:host-gateway"

If the backend is another service in the same Docker Compose network, use the service name:

OPENAPI_URL=http://backend:3000/api/swagger-json

Start with Docker:

docker compose up --build -d

Health check:

curl http://localhost:3000/health

Claude Desktop / Claude Code MCP Setup

Example MCP config:

{
  "mcpServers": {
    "hoppscotch": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MCP_AUTH_TOKEN": "change-me",
        "HOPPSCOTCH_GRAPHQL_URL": "https://hoppscotch.YOUR_DOMAIN/backend/graphql",
        "HOPPSCOTCH_COOKIE": "connect.sid=...; access_token=...; refresh_token=...",
        "OPENAPI_URL": "http://host.docker.internal:3000/api/swagger-json",
        "OPENAPI_BASE_URL": "<<baseUrl>>"
      }
    }
  }
}

Runtime Hoppscotch Auth Update

Credentials are stored in memory only. Restarting the process resets them to env values.

curl http://localhost:3000/admin/hoppscotch-auth \
  -X POST \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connectSid": "...",
    "accessToken": "...",
    "refreshToken": "..."
  }'

The same update is available as hoppscotch_update_auth.

MCP Tools

Team collection tools:

• hoppscotch_list_teams
• hoppscotch_list_team_collections
• hoppscotch_get_team_collection
• hoppscotch_export_team_collection_json
• hoppscotch_export_team_collection
• hoppscotch_inspect_team_collection_tree
• hoppscotch_find_or_create_generated_folder
• hoppscotch_export_team_collections_json
• hoppscotch_list_team_requests
• hoppscotch_get_team_request
• hoppscotch_search_team_requests
• hoppscotch_create_team_request
• hoppscotch_update_team_request
• hoppscotch_move_team_request

OpenAPI sync tool:

• hoppscotch_sync_openapi_to_team_collection

Code-based endpoint tools:

• hoppscotch_analyze_backend_code
• hoppscotch_export_code_endpoint_candidates
• hoppscotch_plan_code_sync_to_team_collection
• hoppscotch_sync_code_to_team_collection
• hoppscotch_create_or_update_request

Personal tools:

• hoppscotch_me
• hoppscotch_list_user_collections
• hoppscotch_get_user_collection
• hoppscotch_export_user_collection_json
• hoppscotch_list_user_requests
• hoppscotch_get_user_request
• hoppscotch_create_user_request
• hoppscotch_update_user_request
• hoppscotch_move_user_request

Usage Examples

List teams:

{}

Use with hoppscotch_list_teams.

Inspect collection tree:

{
  "collectionID": "cmpcn7ozh000h12lc2rtzzx2c",
  "teamID": "cmpcn4aya000g12lcnyif0w3w"
}

Use with hoppscotch_inspect_team_collection_tree.

Export or backup a collection:

{
  "collectionID": "cmqi7d761003v12pbc2kdtdyj",
  "teamID": "cmpcn4aya000g12lcnyif0w3w"
}

Use with hoppscotch_export_team_collection.

OpenAPI dry-run sync:

{
  "teamID": "cmpcn4aya000g12lcnyif0w3w",
  "rootCollectionID": "cmpcn7ozh000h12lc2rtzzx2c",
  "targetCollectionID": "cmqi7d761003v12pbc2kdtdyj",
  "dryRun": true
}

OpenAPI write sync:

{
  "teamID": "cmpcn4aya000g12lcnyif0w3w",
  "rootCollectionID": "cmpcn7ozh000h12lc2rtzzx2c",
  "targetCollectionID": "cmqi7d761003v12pbc2kdtdyj",
  "dryRun": false,
  "deprecatedStrategy": "mark"
}

Code analysis:

{
  "projectPath": "/absolute/path/to/backend",
  "framework": "auto",
  "maxFiles": 500
}

Use with hoppscotch_analyze_backend_code. Full JSON is saved under ./analysis/ and the MCP response returns only a compact summary.

Code sync dry-run:

{
  "analysisFile": "./analysis/backend-1710000000000.analysis.json",
  "teamID": "cmpcn4aya000g12lcnyif0w3w",
  "rootCollectionID": "cmpcn7ozh000h12lc2rtzzx2c",
  "targetCollectionID": "cmqi7d761003v12pbc2kdtdyj",
  "baseUrl": "<<baseUrl>>",
  "dryRun": true
}

Code sync write mode:

{
  "analysisFile": "./analysis/backend-1710000000000.analysis.json",
  "teamID": "cmpcn4aya000g12lcnyif0w3w",
  "rootCollectionID": "cmpcn7ozh000h12lc2rtzzx2c",
  "targetCollectionID": "cmqi7d761003v12pbc2kdtdyj",
  "baseUrl": "<<baseUrl>>",
  "dryRun": false,
  "includeLowConfidence": false,
  "deprecatedStrategy": "ignore"
}

Single request create/update dry-run:

{
  "teamID": "cmpcn4aya000g12lcnyif0w3w",
  "targetCollectionID": "cmqi7d761003v12pbc2kdtdyj",
  "method": "GET",
  "path": "/api/users/{id}",
  "title": "Get user",
  "folderName": "Users",
  "baseUrl": "<<baseUrl>>",
  "pathParams": [{ "key": "id" }],
  "queryParams": [{ "key": "include" }],
  "dryRun": true
}

Code Analysis Coverage

NestJS support uses the TypeScript compiler API and detects:

• @Controller()
• @Get(), @Post(), @Put(), @Patch(), @Delete()
• @Param(), @Query(), @Body(), @Headers()
• @UseGuards(), @ApiTags(), @ApiOperation(), @ApiBearerAuth()
• DTO class names used in @Body() parameters
• source file and line number

Express and Laravel support is heuristic and lower confidence:

• Express: router.get/post/put/patch/delete and app.get/post/put/patch/delete
• Laravel: Route::get/post/put/patch/delete

Mounted routers, Laravel apiResource/resource, FormRequest analysis, and complex dynamic route construction are TODOs.

Security Warnings

• Do not commit cookies or tokens.
• Store secrets in .env or MCP client environment variables.
• Rotate cookies if exposed.
• Prefer a dedicated team workspace.
• Use the Generated collection as the sync target.
• Always run dry-run before write mode.