Lint JavaScript/TypeScript files for code quality issues via @eslint/mcp — official ESLint MCP server

@eslint/mcp v0.3.7 — Official ESLint MCP Server

Install: npm install @eslint/mcp (pulls eslint@^10.5.0, @modelcontextprotocol/sdk, zod) Entry: node_modules/@eslint/mcp/src/mcp-cli.js (ESM, stdio transport) Tools: 1 — lint-files

Tool: lint-files

Schema: { filePaths: string[] } (non-empty array of absolute file paths) Returns: Array of content items — first is an instruction header, then one JSON result per file, then a trailing instruction. Each result JSON contains:

• filePath, errorCount, warningCount, fixableErrorCount, fixableWarningCount, fatalErrorCount
• messages[] — each with ruleId, severity (1=warn, 2=error), message, line, column, endLine, endColumn, messageId
• fix — {range: [start, end], text} for auto-fixable issues
• suggestions[] — {desc, fix} for manual suggestions (e.g. "Remove unused variable", "Use '===' instead of '=='")
• source — full file content
• suppressedMessages[], usedDeprecatedRules[]

Key Gotchas

1. ⚠️ Requires `eslint.config.js` in cwd — ESLint 10 uses flat config exclusively. Without it: "Could not find config file." No fallback. The server's cwd is where you launch node from.
2. ⚠️ Add `"type": "module"` to package.json or the config gets a MODULETYPELESSPACKAGE_JSON warning (it still works but logs a noisy deprecation to stderr).
3. Globals must be declared in config — without languageOptions.globals, console/process/setTimeout trigger no-undef errors. Use @eslint/js recommended + explicit globals.
4. Parse errors block all other rules — a with statement in strict mode causes a fatal parse error; no other rules are evaluated for that file (only 1 error reported instead of many).
5. Batch linting works — pass multiple absolute paths in one call; returns one JSON result per file between the instruction header/footer. Faster than individual calls (13ms for 3 files vs 52ms for 1 file on first call).
6. Non-JS files handled gracefully — .txt files return "File ignored because no matching configuration was supplied" (severity 1 warning, not error). No crash.
7. Nonexistent files handled gracefully — returns text "No files matching '/path' were found." (not an MCP error code).
8. Empty array properly rejected — MCP validation error -32602 with Zod details.
9. First call ~52-66ms (ESLint init + config load), subsequent calls 3-6ms per file.
10. ESM-only — the server uses import syntax; entry point is src/mcp-cli.js (not dist/).

Recommended Config

// eslint.config.js
import js from "@eslint/js";
export default [
  js.configs.recommended,
  {
    languageOptions: {
      globals: { console: "readonly", process: "readonly", setTimeout: "readonly" }
    },
    rules: {
      "no-unused-vars": "warn",
      "no-debugger": "error",
      "eqeqeq": "warn",
      "no-var": "warn",
      "no-eval": "error",
    }
  }
];

Performance

Rules Verified Working

no-unused-vars (with suggestions), no-debugger, eqeqeq (with suggestions), no-var (with fix ranges), no-eval, no-duplicate-case, no-dupe-keys, no-undef — all from @eslint/js recommended + custom rules. Fix ranges include byte offsets and replacement text for auto-fix tooling.