Vale MCP Server

A Model Context Protocol (MCP) server that integrates Vale prose linting into AI coding assistants like Claude Desktop, Cursor, and other MCP-compatible tools.

Overview

This MCP server provides AI assistants with the ability to check files for style and grammar issues using Vale's powerful linting engine. It automatically discovers Vale configuration files and provides formatted, actionable feedback about writing quality.

Quick install

Features

• ✅ File linting: Check any text file for style issues with Vale
• 🔍 Smart configuration discovery: Automatically finds .vale.ini files using Vale's native upward search
• 🎯 Configuration priority: Supports VALE_CONFIG_PATH environment variable for explicit configuration
• 📊 Rich formatting: Returns markdown-formatted results with emojis and severity grouping
• 🛡️ Graceful degradation: Provides helpful installation guidance when Vale isn't installed
• 🐛 Debug mode: Optional debug logging for troubleshooting
• 📦 Style sync: Download Vale style packages with vale_sync tool

System requirements

• Node.js: Version 22 or higher
• Vale: Version 3.0 or higher

Installation

Using npx (no install required)

You can run Vale MCP directly using npx without installing it globally:

npx vale-mcp@latest

This is the recommended approach for most users and is what the quick install badges above use.

Global install via npm

Install the vale-mcp package globally to create a system-wide vale-cli command:

npm install -g vale-mcp

To uninstall:

npm uninstall -g vale-mcp

Build from source

# Clone or navigate to the project directory
cd Vale-MCP

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Install globally (creates a system-wide vale-cli command)
npm run install:global

This creates a global vale-cli command that you can use from anywhere, making it easy to configure in AI assistants.

To uninstall:

npm run uninstall:global

Note: If you're actively developing and making changes, you can skip global installation and use the absolute path to build/index.js instead (see integration examples below).

Using with AI assistants

AI coding assistants that support the MCP standard can integrate the Vale MCP server.

Claude Desktop

Add the Vale MCP server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vale": {
      "command": "npx",
      "args": ["vale-mcp@latest"]
    }
  }
}

Using global install:

{
  "mcpServers": {
    "vale": {
      "command": "vale-cli",
      "args": []
    }
  }
}

For debug mode:

{
  "mcpServers": {
    "vale": {
      "command": "npx",
      "args": ["vale-mcp@latest", "--debug"]
    }
  }
}

Restart Claude Desktop after updating the configuration.

VS Code (GitHub Copilot)

You can also add the Vale MCP server to VS Code manually:

Option A: Command Palette (easiest)

1. Open the Command Palette: Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
2. Run: Type MCP: Add Server and select it
3. Provide server information:
   • Name: vale (or any name you prefer)
   • Type: Select stdio
   • Command: npx (recommended, no install needed), vale-cli (if installed globally), or node
   • Arguments:
     • If using npx: Add vale-mcp@latest
     • If using vale-cli: Leave empty or add --debug
     • If using node: Add the path like /Users/fabri/repos/FrankenMCP/Vale-MCP/build/index.js
4. Choose scope: User configuration (global) or Workspace (project-specific)

Option B: Manual configuration

Add to your VS Code settings file:

Using npx (no install needed):

{
  "github.copilot.chat.mcp.servers": {
    "vale": {
      "command": "npx",
      "args": ["vale-mcp@latest"]
    }
  }
}

Using global install:

{
  "github.copilot.chat.mcp.servers": {
    "vale": {
      "command": "vale-cli",
      "args": []
    }
  }
}

Using absolute path (no global install needed):

{
  "github.copilot.chat.mcp.servers": {
    "vale": {
      "command": "node",
      "args": ["/absolute/path/to/Vale-MCP/build/index.js"]
    }
  }
}

With debug mode:

{
  "github.copilot.chat.mcp.servers": {
    "vale": {
      "command": "npx",
      "args": ["vale-mcp@latest", "--debug"]
    }
  }
}

Verify in VS Code:

• Open GitHub Copilot Chat
• Type /mcp to see available MCP tools
• The Vale tools should appear in the list

Cursor

You can also add the Vale MCP server manually (follow Cursor's MCP documentation):

Using npx (no install needed):

{
  "mcpServers": {
    "vale": {
      "command": "npx",
      "args": ["vale-mcp@latest"]
    }
  }
}

Using global install:

{
  "mcpServers": {
    "vale": {
      "command": "vale-cli"
    }
  }
}

Using absolute path:

{
  "mcpServers": {
    "vale": {
      "command": "node",
      "args": ["/absolute/path/to/Vale-MCP/build/index.js"]
    }
  }
}

Using a specific Vale configuration

You can specify a Vale configuration file using the VALE_CONFIG_PATH environment variable:

{
  "mcpServers": {
    "vale": {
      "command": "npx",
      "args": ["vale-mcp@latest"],
      "env": {
        "VALE_CONFIG_PATH": "/path/to/your/.vale.ini"
      }
    }
  }
}

Usage examples

Once configured, you can ask your AI assistant to:

• "Check docs/guide.md using Vale"
• "Lint this markdown file for style issues"
• "What style issues does Vale find in README.md?"
• "Run vale_sync to download the style packages"
• "Is Vale installed on this system?"

Available tools

The server provides four MCP tools:

vale_status

Check if you have installed Vale and can access it.

Returns:

• Installation status (installed/not installed)
• Vale version (if installed)
• Platform-specific installation instructions (if not installed)

Example usage in AI:

"Is Vale installed on this system?"

vale_sync

Download Vale styles and packages by running vale sync. Use this when you encounter errors about missing styles directories.

Parameters:

• config_path (optional): Path to .vale.ini file. If not provided, uses the server's configured path or searches in the current directory.

Returns:

• Success/failure status
• Output from the sync operation
• Helpful error messages if sync fails

When to use:

• When you see E100 errors: "The path '/path/to/styles' does not exist"
• After creating or updating a .vale.ini file
• When adding new packages to your Vale configuration

Example usage in AI:

"Run vale_sync to download the required styles"

check_file

Lint a file at a specific path against Vale style rules.

Parameters:

• path (required): Absolute or relative path to the file

Returns:

• Formatted markdown with issues grouped by severity
• Detailed issue information (line, column, rule, message, suggestion)
• Summary statistics (errors, warnings, suggestions)
• Structured metadata for programmatic access

Example usage in AI:

"Check the README.md file for style issues"

check_text

Lint AI-generated text against Vale style rules before it's written to a file or artifact.

Parameters:

• text (required): The text content to check with Vale
• text_file_ext (optional): The file extension to apply to the text. Used as the value to Vale's --ext argument. If not specified, the --ext argument is not used. The format for this value is an optional leading dot followed by letters and digits, such as: "md", ".md", "txt", ".txt", or "docx"
• config_path (optional): The path to the config file to use. If not specified, the server's configured path is used.

Returns:

• A JSON object containing Vale's evaluation results.

Example usage in AI:

"Check this text for style issues"

Command-line options

vale-cli [options]

Options:
  --debug, --verbose, -v    Enable debug logging
  --help, -h                Show help message
  --version                 Show version number

Configuration

The server searches for Vale configuration in the following order:

1. Per-file: Configuration discovered from file's directory (for check_file tool)
2. Server-wide: VALE_CONFIG_PATH environment variable
3. Working directory: .vale.ini in process.cwd()
4. Vale defaults: Global configuration or built-in rules

Example .vale.ini

StylesPath = styles
Packages = write-good, proselint

[*]
BasedOnStyles = write-good, proselint

For more information about Vale configuration, see the Vale documentation.

Development

Project structure

Vale-MCP/
├── src/
│   ├── index.ts         # Main MCP server
│   ├── vale-runner.ts   # Vale execution wrapper
│   ├── config.ts        # Configuration management
│   └── types.ts         # TypeScript type definitions
├── build/               # Compiled JavaScript (generated)
├── package.json         # Node.js package configuration
├── tsconfig.json        # TypeScript compiler configuration
└── readme.md           # This file

Building for development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch for changes
npm run watch

# Run the server directly
npm start

Linting

# TypeScript compilation check
npx tsc --noEmit

# Strict unused code check
npx tsc --noUnusedLocals --noUnusedParameters --noEmit

Troubleshooting

Vale not found

If you see errors about missing Vale installation:

macOS:

brew install vale

Linux:

sudo snap install vale

Windows:

choco install vale
# or
scoop install vale

Missing styles directory (E100 errors)

If you see errors like "The path '/path/to/styles' does not exist":

1. Make sure you have a .vale.ini file in your project
2. Run the vale_sync tool through your AI assistant
3. Or manually run: vale sync

Debug mode

Enable debug mode to see detailed logging:

{
  "mcpServers": {
    "vale": {
      "command": "vale-cli",
      "args": ["--debug"]
    }
  }
}

Check the MCP server logs in your AI assistant for detailed information.

Credits

Created by @chrischinchilla and @theletterf

License

MIT License. Refer to the LICENSE file for details.