BjornMelin/grammarly-mcp

Grammarly MCP Server

Single-tool Model Context Protocol (MCP) server for AI detection and plagiarism scoring via Grammarly's web interface. Supports two browser automation providers: Stagehand + Browserbase (default) and Browser Use Cloud (fallback).

What it does

• Automates Grammarly's docs UI to get AI detection and plagiarism percentages
• Rewrites text via Claude to reduce AI detection scores
• Exposes one MCP tool: grammarly_optimize_text

Note: This server interacts with app.grammarly.com through browser automation. It does not use Grammarly APIs.

Table of Contents

• Quick Start
• Features
• Requirements
• Installation
• Provider Selection
• Environment Variables
• Running the Server
• Client Configuration
• Tool: grammarly_optimize_text
• Session Persistence
• How It Works
• Development
• Troubleshooting
• Security Considerations
• Notes and Limitations
• License

Quick Start

Option A: Stagehand + Browserbase (Recommended)

Prerequisites: Node.js 18+, Grammarly Pro account, Browserbase account

# 1. Clone and build
git clone https://github.com/BjornMelin/grammarly-mcp.git
cd grammarly-mcp
pnpm install && pnpm build

# 2. Get Browserbase credentials
# - Sign up at https://www.browserbase.com
# - Create a project, note the Project ID
# - Generate an API key

# 3. Set up Claude Code CLI (for text rewriting)
npm install -g @anthropic-ai/claude-code
claude login

# 4. Configure environment
cp .env.example .env
# Edit .env with your Browserbase credentials

# 5. Add to Claude Code
claude mcp add grammarly -- node $(pwd)/dist/server.js

# 6. Test
claude "Use grammarly_optimize_text with mode score_only on: Hello world test"

Option B: Browser Use Cloud (Legacy)

Prerequisites: Node.js 18+, Grammarly Pro account, Browser Use Cloud account

# 1. Clone and build
git clone https://github.com/BjornMelin/grammarly-mcp.git
cd grammarly-mcp
pnpm install && pnpm build

# 2. Get Browser Use credentials
# - Sign up at https://cloud.browser-use.com
# - Create API key (bu_...)
# - Create profile and sync Grammarly login (profile_...)

# 3. Set up Claude Code CLI
npm install -g @anthropic-ai/claude-code
claude login

# 4. Configure environment
cp .env.example .env
# Set BROWSER_PROVIDER=browser-use and Browser Use credentials

# 5. Add to Claude Code
claude mcp add grammarly -- node $(pwd)/dist/server.js

Features

• Dual provider support: Stagehand + Browserbase (default) or Browser Use Cloud (fallback)
• Session persistence: Browserbase contexts preserve Grammarly login across sessions
• Self-healing automation: Stagehand adapts to DOM changes automatically
• Multi-LLM support: Separate providers for browser automation (STAGEHAND_LLM_PROVIDER) and text rewriting (REWRITE_LLM_PROVIDER)
• Live debug URLs: Real-time browser preview during execution
• Action caching: Optional caching for faster repeated operations
• Structured output: JSON or markdown response formats
• Progress notifications: MCP 2025-11-25 progress tracking support

Requirements

All Configurations

• Node.js 18+

• Grammarly Pro account (for AI detection and plagiarism features)

• Claude Code CLI for text rewriting:

  npm install -g @anthropic-ai/claude-code
  claude login
  

Stagehand Provider (Default)

• Browserbase account
• BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID

Browser Use Provider (Fallback)

• Browser Use Cloud account
• BROWSER_USE_API_KEY and BROWSER_USE_PROFILE_ID
• Browser profile synced with Grammarly login state

Installation

git clone https://github.com/BjornMelin/grammarly-mcp.git
cd grammarly-mcp
pnpm install
pnpm build

Provider Selection

This server supports two browser automation providers:

When to Use Stagehand

• Production workloads requiring reliability
• Need session persistence to avoid re-login overhead
• Want real-time debug visibility
• Require self-healing for Grammarly UI changes

When to Use Browser Use Cloud

• Existing Browser Use Cloud setup
• Prefer simpler natural language task descriptions
• One-off or testing scenarios

Set the provider via environment variable:

BROWSER_PROVIDER=stagehand  # Default
BROWSER_PROVIDER=browser-use  # Fallback

Environment Variables

Environment Isolation

Provider Configuration

Stagehand + Browserbase

Required when BROWSER_PROVIDER=stagehand:

* Required when using Google/Gemini models (the default). Get from aistudio.google.com.

Browser Use Cloud

Required when BROWSER_PROVIDER=browser-use:

LLM Provider Controls

Separate LLM providers for browser automation and text rewriting (can use different providers):

If not set, auto-detects from API keys (priority: OpenAI > Google > Anthropic > Claude Code).

Model Selection

API Keys

* Required when explicitly setting the corresponding LLM provider or for auto-detection.

Timeouts and Logging

Running the Server

pnpm start
# or
node dist/server.js

The server uses stdio transport for MCP communication.

Client Configuration

Configure environment variables in your MCP client. Required:

• BROWSERBASE_API_KEY - From browserbase.com
• BROWSERBASE_PROJECT_ID - From Browserbase dashboard

Automatic Setup

Run the interactive setup script to automatically configure your MCP clients using values from your .env file:

# First, configure your .env file with credentials
cp .env.example .env
# Edit .env with your API keys

# Run the setup script
pnpm setup-clients

The script will:

• Show available MCP clients for your platform
• Let you select which clients to configure
• Back up existing configs before modifying
• Write the appropriate config format (JSON or TOML)

Manual Configuration

claude mcp add grammarly -e BROWSER_PROVIDER=stagehand \
  -e BROWSERBASE_API_KEY=bb_xxx \
  -e BROWSERBASE_PROJECT_ID=xxx \
  -- node /path/to/grammarly-mcp/dist/server.js

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {
        "BROWSER_PROVIDER": "stagehand",
        "BROWSERBASE_API_KEY": "bb_xxx",
        "BROWSERBASE_PROJECT_ID": "xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {
        "BROWSER_PROVIDER": "stagehand",
        "BROWSERBASE_API_KEY": "bb_xxx",
        "BROWSERBASE_PROJECT_ID": "xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {
        "BROWSER_PROVIDER": "stagehand",
        "BROWSERBASE_API_KEY": "bb_xxx",
        "BROWSERBASE_PROJECT_ID": "xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {
        "BROWSER_PROVIDER": "stagehand",
        "BROWSERBASE_API_KEY": "bb_xxx",
        "BROWSERBASE_PROJECT_ID": "xxx"
      }
    }
  }
}

code --add-mcp '{"name":"grammarly","command":"node","args":["/path/to/grammarly-mcp/dist/server.js"]}'

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {
        "BROWSER_PROVIDER": "stagehand",
        "BROWSERBASE_API_KEY": "bb_xxx",
        "BROWSERBASE_PROJECT_ID": "xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {
        "BROWSER_PROVIDER": "stagehand",
        "BROWSERBASE_API_KEY": "bb_xxx",
        "BROWSERBASE_PROJECT_ID": "xxx"
      }
    }
  }
}

[mcp_servers.grammarly]
command = "node"
args = ["/path/to/grammarly-mcp/dist/server.js"]

[mcp_servers.grammarly.env]
BROWSER_PROVIDER = "stagehand"
BROWSERBASE_API_KEY = "bb_xxx"
BROWSERBASE_PROJECT_ID = "xxx"

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/grammarly-mcp/dist/server.js"],
          "env": {
            "BROWSER_PROVIDER": "stagehand",
            "BROWSERBASE_API_KEY": "bb_xxx",
            "BROWSERBASE_PROJECT_ID": "xxx"
          }
        }
      }
    ]
  }
}

Recommended Configurations

{
  "env": {
    "BROWSER_PROVIDER": "stagehand",
    "BROWSERBASE_API_KEY": "bb_xxx",
    "BROWSERBASE_PROJECT_ID": "xxx"
  }
}

{
  "env": {
    "BROWSER_PROVIDER": "stagehand",
    "BROWSERBASE_API_KEY": "bb_xxx",
    "BROWSERBASE_PROJECT_ID": "xxx",
    "CLAUDE_MODEL": "haiku"
  }
}

{
  "env": {
    "BROWSER_PROVIDER": "stagehand",
    "BROWSERBASE_API_KEY": "bb_xxx",
    "BROWSERBASE_PROJECT_ID": "xxx",
    "GOOGLE_GENERATIVE_AI_API_KEY": "xxx",
    "STAGEHAND_LLM_PROVIDER": "google",
    "REWRITE_LLM_PROVIDER": "claude-code",
    "CLAUDE_MODEL": "sonnet"
  }
}

{
  "env": {
    "BROWSER_PROVIDER": "stagehand",
    "BROWSERBASE_API_KEY": "bb_xxx",
    "BROWSERBASE_PROJECT_ID": "xxx",
    "BROWSERBASE_CONTEXT_ID": "ctx_xxx",
    "STAGEHAND_LLM_PROVIDER": "google",
    "GOOGLE_GENERATIVE_AI_API_KEY": "xxx",
    "GOOGLE_MODEL": "gemini-2.5-flash",
    "REWRITE_LLM_PROVIDER": "claude-code",
    "CLAUDE_MODEL": "auto",
    "LOG_LEVEL": "info",
    "LLM_REQUEST_TIMEOUT_MS": "120000",
    "CONNECT_TIMEOUT_MS": "30000"
  }
}

Tool: grammarly_optimize_text

Input Parameters

Output Schema

{
  "final_text": "string",
  "ai_detection_percent": "number | null",
  "plagiarism_percent": "number | null",
  "iterations_used": "number",
  "thresholds_met": "boolean",
  "history": [
    {
      "iteration": "number",
      "ai_detection_percent": "number | null",
      "plagiarism_percent": "number | null",
      "note": "string"
    }
  ],
  "notes": "string",
  "live_url": "string | null",
  "provider": "string"
}

LLM Configuration

This server uses separate LLM providers for browser automation and text rewriting:

Example: Different providers for each task:

# Fast Google for browser automation, quality Claude for rewriting
STAGEHAND_LLM_PROVIDER=google
GOOGLE_MODEL=gemini-2.5-flash
REWRITE_LLM_PROVIDER=claude-code
CLAUDE_MODEL=sonnet

Auto-detection priority (when provider not explicitly set):

1. OpenAI - If OPENAI_API_KEY is set
2. Google - If GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY is set
3. Anthropic - If ANTHROPIC_API_KEY is set
4. Claude Code CLI (fallback) - Uses claude login authentication

Claude model auto-selection (when CLAUDE_MODEL=auto):

Browser Use LLM Options

When using Browser Use Cloud (BROWSER_PROVIDER=browser-use), the automation uses Browser Use's built-in LLM at $0.002/step. Text rewriting still uses the configured REWRITE_LLM_PROVIDER.

Session Persistence

Browserbase contexts allow you to persist Grammarly login state across sessions.

How Persistence Works

1. First run: Server creates a Browserbase session. Use the debug URL to manually log into Grammarly.
2. Note context ID: The context ID appears in server logs or session response.
3. Subsequent runs: Set BROWSERBASE_CONTEXT_ID to skip login.

Setup

# First run - no context, log in manually via debug URL
BROWSERBASE_API_KEY=bb_...
BROWSERBASE_PROJECT_ID=...

# After logging in, add context ID for subsequent runs
BROWSERBASE_CONTEXT_ID=ctx_...

Performance

How It Works

Architecture

MCP Client (Claude Code, Cursor, VS Code, etc.)
    │
    └── grammarly_optimize_text tool
        │
        ├── Provider Abstraction
        │    ├── StagehandProvider (default)
        │    │   ├── BrowserbaseSessionManager
        │    │   ├── Stagehand (observe/act/extract)
        │    │   └── Multi-LLM Client
        │    │
        │    └── BrowserUseProvider (fallback)
        │        └── Browser Use SDK
        │
        └── Rewrite Client (multi-provider text rewriting)
            └── Claude Code / OpenAI / Google / Anthropic

Stagehand Flow

1. Get or create Browserbase session with optional context
2. Initialize Stagehand instance connected to session
3. Navigate to app.grammarly.com
4. Use observe() to find UI elements (new document button, AI detector)
5. Use act() to interact (click, type text)
6. Use extract() with Zod schema to get structured scores
7. Return scores with debug URL

Browser Use Flow

1. Create Browser Use session with synced profile
2. Send natural language task to Browser Use agent
3. Agent navigates Grammarly, pastes text, runs checks
4. Return structured scores

Optimization Loop

1. Initial scoring (iteration 0) on original text
2. In optimize mode: Loop up to max_iterations:
   • LLM (via REWRITE_LLM_PROVIDER) rewrites text based on current scores, tone, domain
   • Re-score via Grammarly
   • Break early if thresholds met
3. Generate summary via configured rewrite LLM provider

Development

Build & Quality

pnpm install        # Install dependencies
pnpm build          # Compile TypeScript
pnpm type-check     # Type checking only
pnpm biome:check    # Lint + format check
pnpm biome:fix      # Auto-fix lint + format
pnpm check-all      # Type check + lint

Testing

pnpm test           # Watch mode
pnpm test:run       # Run once
pnpm test:coverage  # With coverage report
pnpm test:unit      # Unit tests only
pnpm test:integration  # Integration tests

Coverage thresholds (enforced in CI): 85% lines, 85% functions, 75% branches.

Tests use Vitest with V8 coverage. See tests/ for test structure and CLAUDE.md for testing conventions.

Troubleshooting

Server Issues

Server won't start

Check that required environment variables are set:

• Stagehand: BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID
• Browser Use: BROWSER_USE_API_KEY, BROWSER_USE_PROFILE_ID

Tool not appearing in client

• Verify path to dist/server.js is absolute and correct
• Run pnpm build to ensure compilation succeeded
• Restart your MCP client after configuration changes

Stagehand Issues

Browserbase session creation fails

• Verify API key and project ID at browserbase.com
• Check Browserbase dashboard for quota/limits

Context not persisting login

• Ensure you logged into Grammarly while context was active
• Context ID must match the session where login occurred
• Grammarly sessions may expire; re-login if needed

Self-heal failures

• Grammarly UI may have changed significantly
• Try with LOG_LEVEL=debug to see Stagehand observations
• Report persistent issues

Browser Use Issues

Session creation fails

• Verify API key at cloud.browser-use.com
• Check that profile exists and is properly synced

Profile sync issues

• Re-sync your Grammarly login using Browser Use tools
• Grammarly cookies may have expired

Grammarly Issues

AI detection scores are null

Your Grammarly plan may not include AI Detector. This requires Grammarly Pro with AI detection enabled.

Plagiarism scores are null

Plagiarism checking requires Grammarly Pro subscription.

Claude Issues

Authentication errors

Using CLI auth (recommended):

claude logout
claude login

Using API key: Ensure CLAUDE_API_KEY is set correctly.

Security Considerations

• API Keys: Store securely. Never commit to version control.

• Browserbase Contexts: Contain session cookies. Treat context IDs as sensitive.

• Browser Use Profiles: Contain Grammarly session state. Treat profile IDs as sensitive.

• Data Flow: Text passes through:

  1. Browserbase or Browser Use Cloud (browser automation)
  2. Grammarly (via web UI)
  3. Claude API (for rewriting)

  Review each service's privacy policy.

• Local Execution: MCP server runs locally via stdio, not over network.

Notes and Limitations

• Grammarly Pro Required: AI Detector and Plagiarism Checker require Grammarly Pro. Scores return null if unavailable.
• UI Dependency: Automation uses observe/act/extract (Stagehand) or natural language (Browser Use). Grammarly UI changes may affect reliability.
• Text Length: Very long texts may exceed context limits. Consider chunking.
• Rate Limits: Browserbase, Browser Use Cloud, and Grammarly have usage limits.
• Session Limits: Browserbase sessions have timeout limits. Use contexts for persistence.

External Resources

• Browserbase: browserbase.com | Docs
• Stagehand: GitHub | Docs
• Browser Use: cloud.browser-use.com | Docs
• Claude Code: ai-sdk-provider-claude-code
• MCP: modelcontextprotocol.io

License

MIT License - see for details.