vba-lint-mcp
An MCP server providing VBA code inspections, linting, and parse tree analysis -- 65 inspections ported from Rubberduck VBA.
Overview
vba-lint-mcp exposes VBA static analysis capabilities through the Model Context Protocol, enabling AI assistants (Claude Code, etc.) and MCP-compatible tools to perform code quality checks on VBA source files.
The inspection logic is derived from the Rubberduck VBA project -- an open-source VBIDE add-in providing code inspections, refactoring, navigation, and unit testing for VBA developers. This project translates Rubberduck's proven C# inspection patterns to TypeScript and makes them accessible via MCP.
Who is this for?
- VBA developers using Claude Code or other MCP clients for code assistance
- Teams maintaining Excel/Access VBA projects who want automated code quality checks
- Anyone building MCP-based development toolchains that include VBA support
Quick Start
Install
git clone [email protected]:devinmlowe/vba-lint-mcp.git
cd vba-lint-mcp
npm install
npm run generate-parser # Requires Java 17+ (JRE)
npm run build
Configure in Claude Code
Add to your MCP settings (.claude/settings.json or project settings):
{
"mcpServers": {
"vba-lint": {
"command": "node",
"args": ["/path/to/vba-lint-mcp/dist/server.js"],
"env": {
"VBA_LINT_LOG_LEVEL": "warn"
}
}
}
}
First Inspection
Once configured, Claude Code can inspect VBA code directly:
> Inspect this VBA code for issues:
>
> Sub Example()
> Dim x
> Let y = 10
> If True Then
> End If
> End Sub
The server will return diagnostics for missing Option Explicit, implicit variant type, obsolete Let keyword, and the empty If block.
Tools
vba/inspect
Run inspections on a VBA code string.
Example output:
{
"results": [
{
"inspection": "EmptyIfBlock",
"description": "If block is empty and should either contain code or be removed.",
"severity": "warning",
"category": "CodeQuality",
"tier": "A",
"location": { "startLine": 3, "startColumn": 4, "endLine": 4, "endColumn": 10 },
"quickFix": { "description": "Remove the empty If block" },
"suppressed": false
}
],
"errors": [],
"skippedInspections": [],
"parseErrors": [],
"engineVersion": "0.1.0"
}
vba/inspect-workspace
Scan a directory tree for VBA files (.bas, .cls, .frm) and return aggregated results.
In summary mode (default), returns counts by file and inspection. In detailed mode, returns full result objects for each finding.
vba/list-inspections
List all available inspections with metadata.
vba/parse
Parse VBA source code and return the AST.
Useful for understanding code structure. The depth parameter limits serialization size for large modules.
Inspection Catalog
65 inspections across 2 tiers and 8 categories.
Tier A: Parse-Tree Inspections (43)
These inspections analyze the ANTLR4 parse tree directly and require no symbol resolution. They run on both inline code (vba/inspect) and workspace scans.
Tier B: Symbol-Aware Inspections (22)
These inspections require symbol resolution (declaration collection + reference resolution). They run on both inline code and workspace scans, with workspace scans providing cross-module resolution.
Configuration
Host Libraries
The hostLibraries parameter controls which host-specific inspections run. Default is ["excel"]. Excel-specific inspections (ImplicitActiveSheetReference, etc.) only run when "excel" is included.
.vbalintignore
For workspace scanning, create a .vbalintignore file with glob patterns to exclude files:
# Ignore generated code
generated/**
*.generated.bas
# Ignore test fixtures
test/**
Planned Features
The following features are designed but not yet implemented:
.vbalintrc.json (planned)
Project-level configuration file for customizing severity overrides and default host libraries:
{
"hostLibraries": ["excel"],
"severity": {
"EmptyIfBlock": "error",
"StepNotSpecified": "off"
}
}
@Ignore Annotation Suppression (planned)
Inline suppression of specific inspections using VBA comment annotations:
'@Ignore EmptyIfBlock
If condition Then
End If
'@Ignore EmptyIfBlock, ObsoleteLetStatement
Docker
Build
docker build -t vba-lint-mcp .
Run with Docker Compose
docker compose build
docker compose run --rm vba-lint
The MCP server uses stdio transport (stdin/stdout JSON-RPC), so it must be run interactively (docker compose run), not detached (docker compose up).
Mount VBA Files for Workspace Scanning
Edit docker-compose.yml to mount your VBA project directory:
services:
vba-lint:
build: .
stdin_open: true
volumes:
- ./my-vba-project:/data:ro
Then use the vba/inspect-workspace tool with path: "/data".
Image Size
The runtime image uses node:22-alpine with a non-root user. Source files are included for GPL-3.0 compliance.
Development
Setup
npm install
npm run generate-parser # Requires Java 17+
npm run build
Testing
npm test # All tests
npm run test:watch # Watch mode
npx vitest run <path> # Specific test
Adding an Inspection
See CONTRIBUTING.md for a step-by-step guide to adding new inspections.
Project Structure
src/
server.ts # MCP server entry point
inspections/
base.ts # Inspection contracts
registry.ts # Master registration
runner.ts # Tiered execution engine
parse-tree/ # Tier A inspections (by category)
declaration/ # Tier B inspections
parser/ # ANTLR4 parser facade
symbols/ # Symbol resolution (Tier B)
annotations/ # @Ignore annotation parsing
grammar/
VBALexer.g4 # ANTLR4 lexer grammar (from Rubberduck)
VBAParser.g4 # ANTLR4 parser grammar (from Rubberduck)
Known Limitations
- Conditional compilation (
#If,#Const,#Else) is not preprocessed. All branches are parsed as active code, which may produce false positives in modules using conditional compilation. - Tier C inspections (COM type library dependent, Rubberduck annotation system, VBE runtime) are out of scope. See PLAN.md for the full list.
Attribution
This project is a derivative work of Rubberduck VBA. The VBA grammar and inspection logic are translated from Rubberduck's C# codebase.
Copyright (C) Rubberduck Contributors -- Licensed under GPL-3.0.
See ATTRIBUTION.md for the complete attribution, derived works table, and contributor acknowledgment.
License
This project is licensed under the GNU General Public License v3.0. See LICENSE for the full text.
In accordance with GPL-3.0:
- All derived inspection logic retains attribution to Rubberduck VBA
- Every derived file includes a per-file copyright header
- Docker images include full source code (GPL-3.0 Section 6)
- Consumers of this project must comply with GPL-3.0 terms