mcp-access

Give any AI assistant full control over Microsoft Access databases.

Create forms, write VBA, design tables, manage controls, run queries, build relationships, and edit every corner of an .accdb — all through natural language. 68 tools that turn Access into something you can talk to.

No Access expertise required. Just describe what you want.

"Create a form called Invoices with a ListBox, two date filters, and a search button"
"Add a VBA click handler that filters the recordsource by date range"
"Create a table called audit_log with timestamp, user, and action fields"
"List all controls inside the Payment tab and change the combo's row source"

The AI handles the COM automation, design view, VBA modules, binary sections, cache invalidation, and all the ugly parts. You get the result.

What it can do

• Forms & Reports — create, clone, export, import, screenshot, click, type. Full UI automation loop
• VBA — read, write, replace, compile, and run procedures. Line-level or full-proc editing
• Controls — create, delete, modify, list, set tab order. Finds controls nested inside TabControl pages
• Tables & SQL — create via DAO, alter, query, batch execute, full-text search across every Text/Memo field. Linked ODBC tables supported
• Relationships, indexes, references, queries, macros — full CRUD. Clone any object (form / report / module / class / query / macro) preserving VBA and binary sections
• Maintenance — compact & repair, decompile bloated databases, export structure docs. Office install autodetected (no more hardcoded Office 16 paths)
• UI lint — access_lint_form flags objectively broken layouts (white-on-white text, overlaps, truncation, off-canvas controls). A checker, not a designer — see the note below

Works with Claude Code, Cursor, Windsurf, Continue, or any MCP-compatible client.

Requirements

• Windows (COM automation is Windows-only)
• Microsoft Access installed (any version that supports VBE, 2010+)
• Python 3.9+
• "Trust access to the VBA project object model" enabled in Access Trust Center

Installation

pip install mcp pywin32

Enable VBA object model access

File → Options → Trust Center → Trust Center Settings → Macro Settings → check Trust access to the VBA project object model

Or run the included PowerShell script:

.\enable_vba_trust.ps1

Register with Claude Code

Global (available in all projects):

claude mcp add access -- python C:\path\to\access_mcp_server.py

Project-only (creates .mcp.json in current directory):

claude mcp add --scope project access -- python C:\path\to\access_mcp_server.py

Register with other MCP clients

Add to your MCP config file (.mcp.json, mcp.json, or client-specific settings):

{
  "mcpServers": {
    "access": {
      "type": "stdio",
      "command": "python",
      "args": ["C:\\path\\to\\access_mcp_server.py"]
    }
  }
}

Compatible with any MCP-compliant client (Cursor, Windsurf, Continue, etc.).

Tools (68)

Database

Database objects

SQL & tables

VBE line-level editing

Form & report controls

⚠️ A note on access_lint_form — manage your expectations

This is NOT a designer and there is zero super-design here. Don't expect it to make a form look good, suggest a nice palette, or have any taste — it has none and never will.

It is a dumb, deterministic verifier of the obvious, easy-to-check stuff: is the text the same colour as its background? do two controls physically overlap? does a caption not fit its box? is something off the edge of the form, or zero pixels tall? That's it. Plain math — WCAG contrast ratios and rectangle intersection — with a pile of false-positive guards so it doesn't cry wolf.

Think seatbelt, not stylist: it won't make the car pretty, it just stops you shipping a form with white text on a white background without noticing. It runs automatically on every control edit so those obvious mistakes surface on their own. If you were hoping for a UI-design AI, this isn't it (honest PRs to make it smarter are very welcome 😄).

Text export/import

Database properties

Linked tables

Relationships

VBA References

Maintenance

Query management

Indexes

VBA Compilation

VBA & macro execution

⚠️ Disabled by default (v0.7.51). These three tools run arbitrary code and are gated behind the MCP_ACCESS_ALLOW_CODE_EXEC environment variable. See Security to enable them.

Export

Data transfer

Field properties

Startup options

Screenshot & UI automation

Cross-reference

Knowledge base

Typical workflows

Targeted VBA editing (recommended)

1. access_list_objects      → find the module or form name
2. access_vbe_module_info   → get procedure list and line numbers
3. access_vbe_get_proc      → read the specific procedure
4. access_vbe_replace_lines → apply targeted line-level changes
5. access_close             → release the file when done

Full object replacement (forms, reports, modules)

1. access_get_code   → export to text
2. (edit the text)
3. access_set_code   → reimport — binary sections are restored automatically

Creating a new form

1. access_create_form(db, "myForm", has_header=true)  → creates empty form
2. access_create_control(db, "form", "myForm", "CommandButton", {Name: "btn1", ...})
3. access_vbe_append(db, "form", "myForm", code)  → add VBA event handlers
4. access_set_form_property(db, "form", "myForm", {HasModule: true, OnCurrent: "[Event Procedure]"})

Screenshot & UI interaction

1. access_screenshot(db, "form", "myForm")  → capture form as PNG
2. (LLM reads the image and identifies UI elements)
3. access_ui_click(db, x=850, y=120, image_width=1920)  → click a button
4. access_ui_type(db, text="search term")  → type in a field
5. access_ui_type(db, key="enter")  → press Enter
6. access_screenshot(db)  → verify the result

Security

This is a local stdio server with no network surface, so there is no login by design — see SECURITY.md for the full threat model. The main risk is prompt injection: an agent tricked (via db_path or content it reads out of the database) into calling a code-execution tool.

Code execution is disabled by default (v0.7.51). The three tools that run arbitrary VBA/Shell — access_run_vba, access_eval_vba, access_run_macro — are hidden and rejected unless you opt in with an environment variable. To re-enable, add it to this server's env in your MCP client config and restart:

"env": { "MCP_ACCESS_ALLOW_CODE_EXEC": "1" }

Enabling grants arbitrary OS command execution; only point the server at trusted databases. See SECURITY.md for details and how to report issues.

Environment variables

All three are read from the server process, so they go in the env block of your MCP client config and take effect on restart.

About the SHIFT bypass (v0.7.53). Holding SHIFT is how the server skips a database's AutoExec macro and startup form, but the key-down is a global OS event — it is not scoped to Access, so anything you type anywhere on the machine while it is held arrives capitalised (~0.3 s on every database switch, ~3 s per decompile). Turn it off if that bothers you and your databases guard their own startup, which is the cleaner fix and belongs in the database:

If Not Application.UserControl Then
  Exit Function
End If

Application.UserControl is False when Access was started via COM, so the database opts itself out under automation and needs no bypass at all. With the bypass off, AutomationSecurity and the dialog watchdog still apply — but an unguarded AutoExec macro object will run.

About exclusive opens (v0.7.55). Shared opens — the default, and what every version before this one did — cannot take a design lock. Attaching Data Macros via SaveAsText/LoadFromText, or anything routing through DoCmd.OpenTable acViewDesign, is refused for any table another Access session has open, one table at a time and without stopping the run: it finishes, reports success, and nothing changed. Turn the switch on and that becomes a single visible failure when the database is opened.

It is off by default because it is genuinely exclusive: the session holds the database between tool calls, so while the server is connected nobody else can open it. That is right for a build or a development machine and wrong for a shared front-end. access_close releases the database without stopping the server.

The switch also verifies the mode instead of trusting it. Access treats Exclusive:=True as a request: with the file already in use it opens it shared without a word, and when someone else holds it exclusively it raises nothing and leaves the session with no database at all. So the server checks the lock file before opening (refusing without touching the session), checks it again afterwards (closing the database if Access downgraded it), and names the sessions holding it in the error. A stale lock file left by a crashed Access is not mistaken for a live one. With the switch on the server also stops attaching to an already-running Access instance, which would hold the file shared.

When the switch is off, you still get told (v0.7.56). The default stays shared and nothing is refused, but if the database is already open in another Access session the server says so on the result of the call that opened it, naming the sessions holding it. Design work is what silently half-lands in that state, and the person most likely to point the server at a live front-end is the one least likely to know that. A database another process holds exclusively is also reported as a lock conflict now — Access refuses that open without an error and it used to be diagnosed as a broken AutoExec, which sent people hunting through startup code for a locking problem.

Notes

• Access runs visible (Visible = True) so VBE COM access works correctly.
• One Access instance is shared across all tool calls (singleton session). Opening a different .accdb closes the previous one.
• COM thread isolation: All COM calls run in a dedicated single-thread executor (_com_executor) with CoInitialize(). This keeps COM in one STA thread while the asyncio event loop stays free for stdio I/O, preventing -32602 errors from message corruption.
• Auto-reconnect: if the COM session becomes stale (Access crashed, closed manually, or COM corruption), the server detects it via a health check and reconnects automatically on the next tool call.
• access_get_code strips binary sections (PrtMip, PrtDevMode, etc.) from form/report exports — access_set_code restores them automatically before importing.
• All VBE line numbers are 1-based.

Known limitations

• ActiveX controls (type 119 = acCustomControl): access_create_control now accepts a class_name parameter with the ProgID (e.g. Shell.Explorer.2) to initialize the OLE control. For WebBrowser specifically, use type 128 (acWebBrowser) which creates a native control without OLE complexity. Setting ctrl.Class from COM may not work for all ActiveX controls — manual insertion from the ribbon remains the most reliable method.
• access_run_vba: Now supports form module procedures via Forms.FormName.Method syntax (direct COM access, form must be open). Also supports timeout parameter — if exceeded, auto-dismisses MsgBox/InputBox dialogs. For more flexible form interaction, use access_eval_vba.
• Timer events (Form_Timer): Now fire during access_screenshot when wait_ms > 0 — the wait loop pumps Windows messages via pythoncom.PumpWaitingMessages(). Other tools still block the message pump.
• access_vbe_append previously HTML-encoded & as & due to MCP transport escaping. Fixed in v0.7.3 with explicit html.unescape() decoding.

Troubleshooting

Intermittent -32602 Invalid request parameters errors

The MCP Python SDK (v1.26.0) has a catch-all except Exception in mcp/shared/session.py that swallows real errors and returns a generic -32602 code with no detail. A local patch is applied to this machine that includes the actual exception and traceback in the error response. If you upgrade the mcp package, re-apply the patch — see CLAUDE.md for details.

Changelog

See CHANGELOG.md for the full release history.