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:

| Feature | Stagehand (Default) | Browser Use Cloud | | --- | --- | --- | | Provider | Browserbase | Browser Use Cloud | | Automation | observe/act/extract | Natural language tasks | | Self-healing | Yes | Limited | | Session persistence | Context IDs | Profile sync | | Debug URL | Real-time | Per-task | | Action caching | Yes | No | | Reliability | Higher | Moderate |

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

| Variable | Required | Default | Description | | --- | --- | --- | --- | | IGNORE_SYSTEM_ENV | No | false | When true, ignores shell env vars and uses only .env file. Prevents IDE-inherited env pollution. |

Provider Configuration

| Variable | Required | Default | Description | | --- | --- | --- | --- | | BROWSER_PROVIDER | No | stagehand | stagehand or browser-use |

Stagehand + Browserbase

Required when BROWSER_PROVIDER=stagehand:

| Variable | Required | Description | | --- | --- | --- | | BROWSERBASE_API_KEY | Yes | API key from browserbase.com | | BROWSERBASE_PROJECT_ID | Yes | Project ID from Browserbase dashboard | | BROWSERBASE_CONTEXT_ID | No | Persistent context for Grammarly login state | | BROWSERBASE_SESSION_ID | No | Reuse existing session (advanced) | | STAGEHAND_MODEL | No | Deprecated. Use STAGEHAND_LLM_PROVIDER + model vars instead | | STAGEHAND_CACHE_DIR | No | Directory for action caching | | GOOGLE_GENERATIVE_AI_API_KEY | No* | Google API key for Gemini models. Also accepts GEMINI_API_KEY |

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

Browser Use Cloud

Required when BROWSER_PROVIDER=browser-use:

| Variable | Required | Description | | --- | --- | --- | | BROWSER_USE_API_KEY | Yes | API key from cloud.browser-use.com | | BROWSER_USE_PROFILE_ID | Yes | Profile with synced Grammarly login |

LLM Provider Controls

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

| Variable | Required | Default | Description | | --- | --- | --- | --- | | STAGEHAND_LLM_PROVIDER | No | Auto-detect | LLM for browser automation: claude-code, openai, google, anthropic | | REWRITE_LLM_PROVIDER | No | Auto-detect | LLM for text rewriting: claude-code, openai, google, anthropic |

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

Model Selection

| Variable | Required | Default | Description | | --- | --- | --- | --- | | CLAUDE_MODEL | No | auto | Claude model: auto, haiku, sonnet, opus. Auto-selects based on text length and iteration count. | | ANTHROPIC_MODEL | No | claude-sonnet-4-20250514 | Anthropic model id when using direct Anthropic provider. | | OPENAI_MODEL | No | gpt-4o | OpenAI model name | | GOOGLE_MODEL | No | gemini-2.5-flash | Google/Gemini model name |

API Keys

| Variable | Required | Description | | --- | --- | --- | | CLAUDE_API_KEY | No | Claude API key. If not set, uses claude login CLI auth | | OPENAI_API_KEY | No* | OpenAI API key. Required when using OpenAI provider. | | GOOGLE_GENERATIVE_AI_API_KEY | No* | Google API key. Also accepts GEMINI_API_KEY. Required for Google provider. | | ANTHROPIC_API_KEY | No* | Anthropic API key. Required when using direct Anthropic provider. |

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

Timeouts and Logging

| Variable | Required | Default | Description | | --- | --- | --- | --- | | LOG_LEVEL | No | info | debug, info, warn, error | | LLM_REQUEST_TIMEOUT_MS | No | 120000 | LLM request timeout (ms). CLAUDE_REQUEST_TIMEOUT_MS is still accepted for compatibility. | | CONNECT_TIMEOUT_MS | No | 30000 | MCP connection timeout (ms) |

---

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

<details> <summary><b>Claude Code CLI</b></summary>

Via CLI command:

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

Or add to ~/.claude/settings.json:

{
  "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"
      }
    }
  }
}

</details> <details> <summary><b>Claude Desktop</b></summary>

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "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"
      }
    }
  }
}

</details> <details> <summary><b>Cursor</b></summary>

Add to ~/.cursor/mcp.json:

{
  "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"
      }
    }
  }
}

Or via UI: Settings → MCP → Add new MCP Server

</details> <details> <summary><b>VS Code (GitHub Copilot)</b></summary>

Add to .vscode/mcp.json in your workspace:

{
  "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"
      }
    }
  }
}

Or via CLI:

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

</details> <details> <summary><b>Windsurf</b></summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "grammarly": {
      "command": "node",
      "args": ["/path/to/grammarly-mcp/dist/server.js"],
      "env": {