Lint JavaScript files with ESLint via @eslint/mcp — official ESLint MCP server with auto-fix suggestions

@eslint/mcp — Official ESLint MCP Server

Package: @eslint/mcp (npm) — official from the ESLint team Transport: stdio Entry point: src/mcp-cli.js (ships as ESM source, no build step) Deps: @modelcontextprotocol/sdk, eslint v10 Auth: none

Tools (1)

Setup: eslint.config.js REQUIRED

ESLint 10 uses flat config. Without eslint.config.js in the server's CWD, every call returns "Could not find config file". Minimal config:

export default [{ rules: { "no-unused-vars": "warn", "no-var": "error", "eqeqeq": "warn", "prefer-const": "warn" } }];

Start the server with CWD pointing to the project directory that contains eslint.config.js.

Key Findings (6 calls, 100% success)

1. Structured JSON diagnostics — each file returns {filePath, messages[], errorCount, warningCount, fixableErrorCount, fixableWarningCount}. Each message has ruleId, severity (1=warn, 2=error), message, line, column, endLine, endColumn.

1. Auto-fix ranges included — fixable violations include fix: {range: [start, end], text: "replacement"} that can be applied directly to the source.

1. Suggestions array — non-auto-fixable issues provide suggestions[] with desc, messageId, and fix objects for optional transformations (e.g., "Remove unused variable 'foo'").

1. TypeScript ignored by default — .ts files return "File ignored because no matching configuration was supplied" (warn, no error). Need explicit TS parser config (e.g., typescript-eslint).

1. Response includes LLM instructions — output starts with "Before doing anything else, you must display the full list to the user" and ends with fix-consent prompt. Designed for agent consumption.

1. Multi-file batching — pass multiple paths in filePaths[] and get per-file results in one response.

Latency

p50 = 2ms after first call. First call ~23ms (ESLint initialization).

Gotchas

• ⚠️ `eslint.config.js` MUST exist in server CWD — no config = every call fails silently with text error (not MCP error)
• ⚠️ TypeScript requires explicit parser config — just having .ts files isn't enough
• `filePaths` must be absolute — relative paths may fail depending on CWD
• `filePaths` minimum 1 element — empty array triggers MCP validation error -32602
• Nonexistent files → graceful text response, not MCP error
• Severity 2 = error, 1 = warning — matches ESLint convention
• Response text is agent-oriented — includes prompts like "you must display" and "ask the user for confirmation"