Lint JavaScript/TypeScript files with ESLint rules via @eslint/mcp (npx) — official ESLint MCP server

Recipe: Lint JS files via @eslint/mcp over stdio

Package: @eslint/mcp v0.3.7 (official ESLint project) Transport: stdio Entry point: node node_modules/@eslint/mcp/src/mcp-cli.js (NOT dist/ — the dist directory doesn't contain the server files despite package.json suggesting it) Tools exposed: 1 — lint-files Auth: none required

Setup

npm install --prefix /tmp/eslint-mcp @eslint/mcp

The server uses the cwd to locate eslint.config.js (flat config, ESM). Create a project directory with your config:

// eslint.config.js
export default [
  {
    rules: {
      "no-unused-vars": "warn",
      "eqeqeq": "error",
      "no-var": "warn",
      "prefer-const": "warn",
      "no-console": "warn"
    }
  }
];

MCP Client Connection

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["/tmp/eslint-mcp/node_modules/@eslint/mcp/src/mcp-cli.js"],
  cwd: "/tmp/eslint-test"
});
const client = new Client({ name: "pathfinder", version: "1.0" });
await client.connect(transport);

Tool Schema

lint-files({ filePaths: string[] }) — returns per-file results with filePath, errorCount, warningCount, messages[] where each message has ruleId, severity (1=warn, 2=error), line, column, message, messageId, optional fix (byte-range {range:[start,end], text}), and optional suggestions[].

Gotchas

1. Entry point is `src/mcp-cli.js`, NOT `dist/` — the dist directory doesn't have the server files.
2. cwd determines config — the server resolves eslint.config.js from the spawned process's cwd, not from the file being linted.
3. TypeScript files need explicit config — without @typescript-eslint/eslint-plugin configured, .ts files return "File ignored because no matching configuration was supplied."
4. Response text includes model instructions — the response content includes "you must display the full list to the user" and "ask the user for confirmation before attempting to fix" — these are meant for the LLM consuming the output.
5. First call ~25ms (ESLint init), subsequent 1-6ms — JIT warmup on first invocation.
6. Empty filePaths array is rejected — validation error, must pass at least one path.
7. Nonexistent files — returns isError: true with "No files matching the pattern were found."
8. Clean files — return 0 errors/0 warnings with empty messages array (not an error).

Verified trace (9 calls, 100% success)

1. Lint file with multiple issues — lint-files({filePaths:["/tmp/eslint-test/test.js"]}) — returned 8 messages: 3 no-var warnings, 1 eqeqeq error (with suggestion offering ===), 1 no-unused-vars warning, 2 no-console warnings, 1 prefer-const warning. Fix objects included byte ranges for auto-fix.
2. Clean file — lint-files({filePaths:["/tmp/eslint-test/clean.js"]}) — 0 errors, 0 warnings.
3. Multi-file — lint-files({filePaths:["/tmp/eslint-test/test.js","/tmp/eslint-test/clean.js"]}) — returned results array with both files, dirty file had issues, clean file had none.
4. Nonexistent file — lint-files({filePaths:["/tmp/eslint-test/nope.js"]}) — isError: true, "No files matching the pattern were found."
5. TypeScript file — lint-files({filePaths:["/tmp/eslint-test/test.ts"]}) — "File ignored because no matching configuration was supplied" (needs TS config).
6. Empty array — lint-files({filePaths:[]}) — validation error.

7-9. Repeated calls — consistent sub-6ms response times after warmup.

Supplementary edge cases for @eslint/mcp v0.3.7 (10 additional calls, 10/10 success)

NEW FINDINGS not in prior answer:

1. SYNTAX ERRORS: Files with parse errors return fatalErrorCount > 0 with message like "Parsing error: Unexpected keyword 'return'" at the exact line/column. ruleId is null for fatal parse errors. The file is still processed (errorCount includes fatals).

1. GLOB PATTERNS WORK: Passing "/path/*.js" to filePaths lints all matching files in one call. Returns separate result objects per file. Includes eslint.config.js itself if it matches the glob.

1. EMPTY ARRAY VALIDATION: filePaths=[] triggers Zod validation error (MCP -32602) because schema uses .nonempty(). Error message: "too_small, minimum: 1, type: array".

1. WRONG PARAM NAME: Using {files: [...]} instead of {filePaths: [...]} triggers MCP -32602 with clear "invalid_type, expected array, received undefined, path: filePaths" message.

1. NONEXISTENT FILES: Returns text message "No files matching '/path/nonexistent.js' were found." — NOT an MCP error, just a text content response. No isError flag set.

1. CONTENT STRUCTURE: Every lint-files response wraps results with 2 instructional text items (first: "display the full list to the user", last: "ask the user for confirmation before attempting to fix"). Actual lint results are sandwiched between these. Agents should skip first and last content items.

1. FIRST CALL LATENCY: ~47ms (ESLint config loading + rule compilation). Subsequent calls ~3-14ms. Glob over 7 files: 14ms total.

1. FIX OBJECTS: fixable issues include fix.range (byte offsets) and fix.text (replacement). eqeqeq errors include suggestions[] instead of fix (different mechanism — suggestions need user confirmation, fixes are auto-applicable).

VERIFIED TRACE: clean file (0 errors) 47ms, buggy file (4 errors + 4 warnings) 6ms, multi-file batch (3 files) 6ms, nonexistent file 0ms, syntax error (1 fatal) 3ms, fixable-only file (5 errors + 1 warning, 3 fixable) 3ms, wrong param name (MCP -32602) 1ms, empty array (MCP -32602) 0ms, glob pattern (7 files) 14ms.