GraphQL Grab

The Ultimate GraphQL DevTool - Capture, analyze, test, and generate code from any GraphQL API. No mitmproxy. No certificates. No Python scripts.

npm install -g graphql-grab

100% Free - All Features Unlocked

• Unlimited request captures
• All export formats (cURL, Postman, Insomnia, HAR)
• TypeScript/JavaScript/Python code generation
• React Query, Apollo, Urql hook generation
• Security scanning with SARIF output
• Mock server with chaos engineering
• WebSocket subscription support
• Session management (auth updates, deduplication, merging)
• AI integration via MCP server (Claude, Cursor, etc.)
• Interactive TUI dashboard
• VS Code extension
• No account or license required

Quick Start

# 1. Capture GraphQL requests (auto-configures system proxy)
gqlgrab capture --auto

# 2. Generate TypeScript client with React Query hooks
gqlgrab codegen session.json -f react-query

# 3. Generate test files from captured data
gqlgrab testgen session.json --mocks

# 4. Set up environments for dev/staging/prod
gqlgrab env create staging --endpoint https://staging.api.com/graphql
gqlgrab replay session.json -e staging --diff

# 5. Start mock server for testing
gqlgrab mock session.json

Features at a Glance

| Category | Features | |----------|----------| | Capture | Proxy capture with auto-config, HAR import, WebSocket subscriptions | | Export | cURL, Postman, Insomnia, HAR | | Code Gen | TypeScript, JavaScript, Python with full response types | | Test Gen | Vitest/Jest test files from captured data with mocks | | Frameworks | React Query, Apollo Client, Urql hooks | | Environments | Dev/staging/prod configs with variable substitution | | Sessions | List, update-auth, clean/dedupe, merge multiple sessions | | Testing | Mock server, replay with diff, field fuzzing | | Security | 12-point scanner, SARIF output, schema diff CI | | AI Integration | MCP server for Claude, Cursor, and AI coding assistants | | DevEx | TUI dashboard, watch mode, VS Code extension |

Installation

npm install -g graphql-grab

# Or with your preferred package manager
pnpm add -g graphql-grab
yarn global add graphql-grab

Commands

Capture & Import

gqlgrab capture - Real-time proxy capture

gqlgrab capture [options]

Options:
  -p, --port <port>       Proxy server port (default: 8080)
  -o, --output <file>     Output session file (default: session.json)
  -a, --auto              Auto-configure system proxy (zero setup!)
  --https                 Enable HTTPS proxy with self-signed cert
  --introspect            Auto-fetch schemas from detected endpoints
  --include <patterns>    Only capture matching operations
  --exclude <patterns>    Exclude matching operations

Zero-config capture (recommended):

gqlgrab capture --auto
# System proxy is configured automatically
# Use your browser/app normally
# Press Ctrl+C to save session (proxy settings restored)

Manual setup:

gqlgrab capture -p 9090 --introspect
# Configure browser proxy to 127.0.0.1:9090
# Press Ctrl+C to save session

gqlgrab analyze - Import from HAR file

gqlgrab analyze <har-file> -o session.json

Export HAR from Chrome DevTools: Network tab → Right-click → "Save all as HAR with content"

Export

gqlgrab export - Export to any format

gqlgrab export session.json -f postman,curl,insomnia,har

| Format | Description | |--------|-------------| | curl | Shell commands with curl | | postman | Postman Collection v2.1 | | insomnia | Insomnia REST Client export | | har | HTTP Archive format 1.2 |

Code Generation

gqlgrab codegen - Generate typed clients

gqlgrab codegen session.json [options]

Options:
  -l, --language <lang>      typescript, javascript, python (default: typescript)
  -o, --output <dir>         Output directory (default: ./generated)
  -f, --framework <fw>       none, react-query, apollo, urql (default: none)
  --name <name>              Client class name (default: GraphQLClient)
  --no-responses             Skip response type generation

Examples:

# TypeScript with React Query hooks
gqlgrab codegen session.json -f react-query

# Apollo Client hooks
gqlgrab codegen session.json -f apollo

# Python with TypedDict
gqlgrab codegen session.json -l python

# Plain JavaScript
gqlgrab codegen session.json -l javascript

Generated Output (React Query):

// Types inferred from actual API responses
export interface GetUserResponse {
  user: {
    id: string;
    name: string;
    email: string;
    posts: Array<{
      id: string;
      title: string;
    }>;
  };
}

// Ready-to-use hook
export function useGetUser(variables: GetUserVariables) {
  return useQuery({
    queryKey: ['GetUser', variables],
    queryFn: () => client.getUser(variables),
  });
}

Test Generation

gqlgrab testgen - Generate test files from captured data

gqlgrab testgen session.json [options]

Options:
  -o, --output <dir>       Output directory (default: ./tests/generated)
  -f, --framework <fw>     vitest, jest (default: vitest)
  -l, --language <lang>    typescript, javascript (default: typescript)
  -g, --group-by <mode>    operation, file, domain (default: file)
  --snapshots              Include snapshot tests
  --mocks                  Generate mock response files

Examples:

# Generate Vitest tests with mocks
gqlgrab testgen session.json --mocks

# Jest tests with snapshots
gqlgrab testgen session.json -f jest --snapshots

# One test file per operation
gqlgrab testgen session.json -g operation

Generated test example:

describe('GetUser', () => {
  it('returns a valid response', async () => {
    const result = await client.request(`
      query GetUser($id: ID!) { user(id: $id) { id name } }
    `, { id: "123" })

    expectValidResponse(result)
  })

  it('response has expected shape', async () => {
    const result = await client.request(...)
    expectShape(result.data, { user: 'object' })
  })
})

Environments

gqlgrab env - Manage dev/staging/prod configurations

# Create environments
gqlgrab env create staging --endpoint https://staging.api.com/graphql
gqlgrab env create prod --endpoint https://api.example.com/graphql \
    -H "Authorization:Bearer {{TOKEN}}"

# List environments
gqlgrab env list

# Switch active environment
gqlgrab env use staging

# Show environment details
gqlgrab env show staging

# Update environment
gqlgrab env update staging --set-header "X-Debug:true"

# Delete environment
gqlgrab env delete staging --force

Variable substitution:

# Create env with variables
gqlgrab env create staging \
    --endpoint https://staging.api.com/graphql \
    -V "API_VERSION=v2,DEBUG=true" \
    -H "Authorization:Bearer {{TOKEN}}"

# Variables are substituted at runtime
# {{VAR_NAME}} in headers/endpoints replaced with values

Replay & Regression Testing

gqlgrab replay - Re-run requests and compare responses

gqlgrab replay session.json [options]

Options:
  -e, --env <name>         Use environment configuration
  --endpoint <url>         Target endpoint (overrides env)
  -d, --diff               Enable diff mode - compare responses
  -o, --operation <name>   Filter to specific operation(s)
  --output <file>          Save results to JSON
  --fail-fast              Stop on first error
  --dry-run                Preview what would be replayed

Examples:

# Replay against staging with diff comparison
gqlgrab replay session.json -e staging --diff

# Compare specific operation
gqlgrab replay session.json -o GetUser --diff

# CI/CD - fail on errors or changes
gqlgrab replay session.json --diff --fail-fast

Exit codes for CI:

• 0 - All requests successful, no changes
• 1 - Errors occurred during replay
• 2 - Changes detected in responses (diff mode)

Diff output:

✓ GetUser (query) 45ms
△ GetPosts (query) 52ms
    ~ posts.length:
      - 5
      + 6
    + posts[5]: {"id": "new-post", "title": "New Post"}
✗ UpdateUser (mutation) 0ms
    Error: Unauthorized

Mock Server

gqlgrab mock - Start mock GraphQL server

gqlgrab mock session.json [options]

Options:
  -p, --port <port>      Server port (default: 4000)
  -l, --latency <ms>     Add artificial latency
  --chaos <percent>      Random failure rate (0-100)
  --cors                 Enable CORS (default: true)
  -r, --record <file>    Record unmatched requests
  -d, --dynamic          Reflect variables in responses

Examples:

# Basic mock server
gqlgrab mock session.json

# Chaos engineering - 10% failure rate
gqlgrab mock session.json --chaos 10 --latency 200

# Record unmatched requests for later capture
gqlgrab mock session.json -r unmatched.json

Security

gqlgrab scan - Security scanner

Comprehensive security analysis with 12 checks:

gqlgrab scan session.json [options]

Options:
  -s, --severity <level>   all, critical, high, medium, low (default: all)
  -f, --format <format>    text, json, sarif (default: text)
  -o, --output <file>      Save results to file

Security Checks: | ID | Check | Severity | |----|-------|----------| | GQL-001 | Introspection enabled | Medium | | GQL-002 | Query batching enabled | Low | | GQL-003 | Sensitive data exposure | High | | GQL-004 | Inconsistent authentication | Medium | | GQL-005 | Credentials in variables | High | | GQL-006 | Deep query allowed | Medium | | GQL-007 | Excessive field aliases | Low | | GQL-008 | Debug info in errors | Medium | | GQL-009 | File path exposure | Medium | | GQL-010 | No rate limiting | Low | | GQL-011 | Potential IDOR vector | Info | | GQL-012 | Unauthenticated mutations | High |

SARIF Output for GitHub:

gqlgrab scan session.json -f sarif -o results.sarif
# Upload to GitHub Code Scanning

gqlgrab fuzz - Security fuzzing

Test API resilience with injection payloads:

gqlgrab fuzz session.json [options]

Options:
  -t, --target <url>       Override target endpoint
  -o, --operation <name>   Filter to specific operation
  -p, --payloads <file>    Custom payloads JSON
  --dry-run                Preview without sending
  --output <file>          Save results

Payload Categories:

• SQL injection (sqli)
• Cross-site scripting (xss)
• Insecure direct object references (idor)
• Authentication bypass (auth)
• Buffer overflow (overflow)
• Command injection
• Path traversal

Example:

# Preview what would be tested
gqlgrab fuzz session.json --dry-run

# Fuzz specific operation
gqlgrab fuzz session.json -o GetUser --output results.json

gqlgrab schema-diff - CI/CD schema validation

Detect breaking changes between schemas:

gqlgrab schema-diff <base-schema> [options]

Options:
  -e, --endpoint <url>     Target endpoint to compare
  -H, --headers <headers>  Auth headers (key:value,key:value)
  --fail-on-breaking       Exit code 1 if breaking changes (for CI)
  -o, --output <file>      Save diff to JSON

CI/CD Pipeline Example:

# GitHub Actions
- name: Check for breaking changes
  run: |
    gqlgrab schema-diff schema.json \
      -e https://staging.api.com/graphql \
      --fail-on-breaking

Change Categories:

• Breaking: Removed types/fields, incompatible type changes, added required args
• Dangerous: Nullability changes, added enum values
• Non-breaking: Added types/fields, added optional args

WebSocket Subscriptions

gqlgrab subscribe - WebSocket client

Connect to GraphQL subscriptions:

gqlgrab subscribe <input> [options]

Options:
  -e, --endpoint <url>     Override WebSocket endpoint
  -p, --protocol <proto>   graphql-ws or subscriptions-transport-ws
  -t, --timeout <ms>       Connection timeout (default: 30000)
  -o, --operation <name>   Subscription to run
  -v, --variables <json>   Variables as JSON
  -m, --max-messages <n>   Max messages to receive (default: 100)
  --output <file>          Save messages to JSON

Examples:

# From captured session
gqlgrab subscribe session.json

# Direct WebSocket connection
gqlgrab subscribe wss://api.example.com/graphql \
  -o "subscription { newMessage { id text } }" \
  -t 60000

# Legacy Apollo protocol
gqlgrab subscribe session.json -p subscriptions-transport-ws

Developer Experience

gqlgrab dashboard - Interactive TUI

Browse sessions in an interactive terminal UI:

gqlgrab dashboard session.json

Keyboard Controls: | Key | Action | |-----|--------| | ↑/↓ or j/k | Navigate | | Enter | Select/View details | | o | Operations list | | e | Errors view | | s | Search | | f | Filter (all/query/mutation) | | t | Toggle sort | | q | Back/Quit |

gqlgrab watch - Watch mode

Auto-regenerate on file changes:

gqlgrab watch <input> [options]

Options:
  -m, --mode <mode>        analyze, codegen, schema
  -o, --output <path>      Output path
  -l, --language <lang>    For codegen mode
  -f, --framework <fw>     For codegen mode
  -i, --interval <ms>      Schema poll interval (default: 30000)

Examples:

# Auto-analyze HAR file changes
gqlgrab watch network.har -o session.json

# Auto-regenerate TypeScript client
gqlgrab watch session.json -m codegen -f react-query

# Poll endpoint for schema changes
gqlgrab watch https://api.example.com/graphql -m schema -i 60000

Analysis & Reports

gqlgrab stats - Performance analytics

gqlgrab stats session.json

Output includes:

• Response time percentiles (P50, P95, P99)
• Slowest operations ranking
• Success/error rates
• Response time histogram

gqlgrab complexity - Query complexity analysis

gqlgrab complexity session.json --threshold 50

Calculates complexity scores to identify expensive queries.

gqlgrab report - Generate documentation

gqlgrab report session.json --format html -o report.html
gqlgrab report session.json --format markdown -o report.md

gqlgrab auth-detect - Authentication analysis

gqlgrab auth-detect session.json --extract

Detects Bearer tokens, API keys, session cookies, and extracts to .env.auth.

Session Management

gqlgrab session list - Find session files

List all session files in the current directory:

gqlgrab session list [options]

Options:
  -d, --dir <path>    Directory to search (default: current)

Output:

Sessions

  api-session.json
    Requests: 45 (32Q/13M/0S)
    Domains: api.example.com
    Size: 156.2 KB
    Modified: 12/29/2025, 10:30:00 AM

  backup-session.json
    Requests: 12 (10Q/2M/0S)
    Domains: staging.api.com
    Size: 45.8 KB
    Modified: 12/28/2025, 3:15:00 PM

gqlgrab session update-auth - Update authentication

Update auth headers across all requests in a session (for expired tokens):

gqlgrab session update-auth <session-file> [options]

Options:
  --token <token>        Set Bearer token
  --cookie <cookie>      Set Cookie header
  --headers <headers>    Set headers (key:value,key:value)
  --remove <headers>     Remove headers (comma-separated)

Examples:

# Update Bearer token
gqlgrab session update-auth session.json --token "new-jwt-token"

# Update multiple headers
gqlgrab session update-auth session.json \
  --headers "Authorization:Bearer xyz,X-API-Key:abc123"

# Remove old headers and add new ones
gqlgrab session update-auth session.json \
  --remove "X-Old-Header" \
  --token "fresh-token"

gqlgrab session clean - Clean up sessions

Remove duplicates, errors, and trim sessions:

gqlgrab session clean <session-file> [options]

Options:
  -o, --output <file>       Output file (default: overwrite input)
  --no-dedupe               Don't remove duplicates
  --remove-errors           Remove requests with errors
  --keep-latest <n>         Keep only latest N requests
  --min-duration <ms>       Remove requests slower than N ms

Examples:

# Deduplicate (default behavior)
gqlgrab session clean session.json

# Clean up for CI - remove errors, keep latest 50
gqlgrab session clean session.json \
  --remove-errors \
  --keep-latest 50 \
  -o clean-session.json

gqlgrab session merge - Merge sessions

Combine multiple session files:

gqlgrab session merge <sessions...> [options]

Options:
  -o, --output <file>    Output file (required)
  --no-dedupe            Don't remove duplicates

Examples:

# Merge multiple captures
gqlgrab session merge day1.json day2.json day3.json -o week.json

# Merge without deduplication
gqlgrab session merge *.json -o all-sessions.json --no-dedupe

AI Integration (MCP Server)

GraphQL Grab includes an MCP (Model Context Protocol) server that allows AI assistants like Claude, Cursor, and other AI coding tools to directly interact with your captured GraphQL sessions.

Setup

Add to your AI assistant's MCP configuration:

Claude Code / Cursor:

{
  "mcpServers": {
    "graphql-grab": {
      "command": "npx",
      "args": ["graphql-grab", "mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "graphql-grab": {
      "command": "gqlgrab-mcp"
    }
  }
}

Available AI Tools

| Tool | Description | |------|-------------| | analyze_session | Get structured analysis of all operations, types, and patterns | | get_operations | List queries/mutations/subscriptions with filtering | | get_operation_details | Full details for a specific operation (query, variables, response) | | generate_types | Generate TypeScript types from captured responses | | security_scan | Run security analysis and get findings | | get_api_summary | High-level API summary (domains, auth patterns, stats) | | analyze_har | Extract GraphQL requests from Chrome HAR exports | | suggest_tests | Generate test case suggestions for operations |

Example AI Interactions

With the MCP server configured, you can ask your AI assistant:

• "Analyze my session.json and tell me what APIs are being called"
• "Generate TypeScript types for the GetUser operation"
• "Run a security scan on my captured requests"
• "What auth patterns is this API using?"
• "Suggest test cases for the mutations in my session"

The AI will use the MCP tools to read your session files and provide accurate, context-aware responses.

CI/CD Integration

All commands support --json flag for machine-readable output:

gqlgrab stats session.json --json
gqlgrab scan session.json --json
gqlgrab schema-diff schema.json -e https://api.com --json

GitHub Actions Example:

name: GraphQL API Checks

on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install GraphQL Grab
        run: npm install -g graphql-grab

      # Set up environment for staging
      - name: Configure Environment
        run: |
          gqlgrab env create staging \
            --endpoint ${{ secrets.STAGING_API_URL }} \
            -H "Authorization:Bearer ${{ secrets.STAGING_TOKEN }}"

      # Regression testing - compare with captured baseline
      - name: Replay Regression Tests
        run: gqlgrab replay session.json -e staging --diff --fail-fast

      # Security scan
      - name: Security Scan
        run: gqlgrab scan session.json -f sarif -o results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

      # Schema validation
      - name: Schema Breaking Changes
        run: |
          gqlgrab schema-diff schema.json \
            -e ${{ secrets.STAGING_API_URL }} \
            --fail-on-breaking

VS Code Extension

Install from the VS Code Marketplace or build from packages/vscode-extension/.

Features:

• Activity bar with session explorer
• Start/stop capture from VS Code
• Right-click to generate code or export
• Security scan integration
• Interactive dashboard in terminal

Session Format

{
  "version": "1.0",
  "created": "2025-01-01T00:00:00Z",
  "requests": [{
    "id": "uuid",
    "operationName": "GetUser",
    "operationType": "query",
    "query": "query GetUser($id: ID!) { user(id: $id) { id name } }",
    "variables": { "id": "123" },
    "response": {
      "status": 200,
      "data": { "user": { "id": "123", "name": "John" } }
    },
    "headers": { "Authorization": "Bearer ..." },
    "url": "https://api.example.com/graphql",
    "timestamp": 1704067200000,
    "duration": 45
  }],
  "stats": {
    "totalRequests": 10,
    "queries": 7,
    "mutations": 3,
    "subscriptions": 0,
    "domains": ["api.example.com"]
  }
}

Comparison

| Feature | GraphQL Grab | mitmproxy | Charles Proxy | Postman | |---------|--------------|-----------|---------------|---------| | Setup time | 30 seconds | 45+ minutes | 30+ minutes | 5 minutes | | Auto proxy config | ✅ --auto flag | ❌ Manual | ❌ Manual | N/A | | GraphQL-aware | ✅ Yes | ❌ No | ❌ No | ⚠️ Limited | | Code generation | ✅ TS/JS/Python | ❌ No | ❌ No | ❌ No | | Test generation | ✅ Vitest/Jest | ❌ No | ❌ No | ❌ No | | Framework hooks | ✅ RQ/Apollo/Urql | ❌ No | ❌ No | ❌ No | | Environments | ✅ Built-in | ❌ No | ❌ No | ✅ Paid | | Replay with diff | ✅ Built-in | ❌ No | ❌ No | ❌ No | | Mock server | ✅ Built-in | ❌ No | ❌ No | ✅ Paid | | Security scanning | ✅ 12 checks + SARIF | ❌ No | ❌ No | ❌ No | | WebSocket support | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Limited | | AI integration | ✅ MCP Server | ❌ No | ❌ No | ❌ No | | CI/CD ready | ✅ JSON + SARIF | ⚠️ Manual | ❌ No | ⚠️ API | | Price | Free | Free | $50 | $12/mo |

Troubleshooting

Proxy not capturing?

• Verify proxy settings: 127.0.0.1:8080
• Use --https for HTTPS traffic
• Check firewall settings

WebSocket not connecting?

• Try -p subscriptions-transport-ws for older servers
• Check endpoint URL starts with ws:// or wss://

Code generation types incorrect?

• Capture more requests for better type inference
• Use --no-responses if response types aren't needed

Support

• Website: https://grabgraphql.com
• Documentation: https://grabgraphql.com/docs
• Issues: GitHub Issues

License

MIT License