Microsoft Access Database

mcp-access

让任意 AI 助手完全控制 Microsoft Access 数据库。

通过自然语言创建窗体、编写 VBA、设计表、管理控件、运行查询、建立关系，并编辑 .accdb 的方方面面。69 个工具，让你可以通过对话来使用 Access。

无需掌握 Access。只需描述你的需求。

"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"

AI 会处理 COM 自动化、设计视图、VBA 模块、二进制区段、缓存失效，以及所有棘手的部分。你只需获得结果。

能做什么

• 窗体和报表 — 创建、克隆、导出、导入、截屏、单击、输入。完整的 UI 自动化流程
• VBA — 读取、编写、替换、编译并运行过程。支持逐行或整个过程编辑
• 控件 — 创建、删除、修改、列出、设置 Tab 顺序。可查找嵌套在 TabControl 页面中的控件
• 表和 SQL — 通过 DAO 创建、修改、查询、批量执行，并跨所有 Text/Memo 字段进行全文搜索。支持链接的 ODBC 表
• 关系、索引、引用、查询、宏 — 完整的 CRUD 操作。可克隆任意对象（窗体 / 报表 / 模块 / 类 / 查询 / 宏），并保留 VBA 和二进制区段
• 维护 — 压缩并修复、反编译臃肿的数据库、导出结构文档。自动检测 Office 安装位置（不再硬编码 Office 16 路径）
• UI 检查 — access_lint_form 会标记客观上存在问题的布局（白底白字、重叠、文本截断、控件超出画布）。它是检查工具，不是设计工具 — 请参阅下方说明

可与 Claude Code、Cursor、Windsurf、Continue 或任何兼容 MCP 的客户端搭配使用。

---

要求

• Windows（COM 自动化仅支持 Windows）
• 已安装 Microsoft Access（支持 VBE 的任意版本，2010+）
• Python 3.10+
• 在 Access 信任中心启用*"信任对 VBA 工程对象模型的访问"*

安装

pip install "mcp>=1.0.0,<2" pywin32 pillow

启用 VBA 对象模型访问权限

文件 → 选项 → 信任中心 → 信任中心设置 → 宏设置 → 勾选 信任对 VBA 工程对象模型的访问

或者运行随附的 PowerShell 脚本：

.\enable_vba_trust.ps1

注册到 Claude Code

全局（在所有项目中均可用）：

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

仅限项目（在当前目录中创建 .mcp.json）：

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

注册到其他 MCP 客户端

添加到 MCP 配置文件（.mcp.json、mcp.json 或客户端专属设置）：

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

兼容任何符合 MCP 规范的客户端（Cursor、Windsurf、Continue 等）。

工具（69 个）

数据库

工具	描述
access_create_database	创建新的空 .accdb 数据库文件
access_close	关闭 COM 会话并释放 .accdb 文件

数据库对象

工具	描述
access_list_objects	按类型列出对象（table、module、form、report、query、macro、all）。已过滤系统表
access_get_code	将对象的完整定义导出为文本
access_set_code	将修改后的文本导入回去（创建或覆盖）
access_export_structure	生成包含所有模块、窗体、报表和查询的 Markdown 索引
access_delete_object	删除模块、窗体、报表、查询或宏。需要 confirm=true
access_create_form	创建新窗体，且不会触发阻塞 COM 的“另存为”MsgBox。可选参数包括 has_header（用于标题/页脚节）、record_source（绑定到表/查询）、default_view（0=单窗体，1=连续窗体，2=数据表，...）

SQL 和表

工具	描述
access_execute_sql	通过 DAO 运行 SQL——SELECT 会以 JSON 返回行（limit 默认值为 500）。DELETE/DROP/ALTER 需要 confirm_destructive=true
access_execute_batch	在一次调用中执行多条 SQL 语句。支持混合使用 SELECT/INSERT/UPDATE/DELETE，并提供逐条语句的结果、stop_on_error 和 confirm_destructive
access_table_info	通过 DAO 显示表结构（字段、类型、大小、必填状态、链接状态）
access_search_queries	一次搜索所有查询 SQL 中的文本（查找哪些查询引用了某个表、字段或关键词）
access_create_table	通过 DAO 创建表，并在一次调用中完整支持类型、默认值、描述和主键。比 CREATE TABLE SQL 更可靠
access_alter_table	通过 DAO 修改表结构：添加字段、删除字段（需要 confirm=true）、重命名字段

VBE 行级编辑

工具	描述
access_vbe_get_lines	读取 VBA 模块中的指定行范围，无需导出整个文件
access_vbe_get_proc	按名称获取过程代码及其位置
access_vbe_module_info	列出所有过程及其行号
access_vbe_replace_lines	直接通过 VBE 替换、插入或删除 VBA 模块中的行
access_vbe_find	在某个指定模块中搜索文本。若命中以 _ 换行的语句，也会返回拼接后的完整语句。若要一次搜索所有模块，请使用 access_vbe_search_all
access_vbe_search_all	一次在数据库中的所有模块/窗体/报表中搜索文本。若命中以 _ 换行的语句，也会返回拼接后的完整语句。可选的 context_lines（0-10）会随每个命中结果返回其周围代码
access_vbe_replace_proc	按名称替换整个过程（自动计算行范围）。会移除位置不当的 Option 行，并运行结构健康检查
access_vbe_patch_proc	在过程中进行精准查找和替换。默认原子性（补丁失败时不会写入任何内容），锚点不区分大小写，支持可选的 require_unique，并在补丁失败时使用容忍空白差异的备用匹配及上下文错误消息。proc_name='(Declarations)' 会指定声明部分
access_vbe_append	在模块末尾追加代码。自动移除 Option Explicit/Option Compare，以避免其位置不当

窗体和报表控件

工具	描述
access_list_controls	列出窗体/报表的所有控件及其关键属性。导出内容中跨行的长值会合并后返回。Pages/OptionGroups 中的控件包含 parent 字段。可选的 fields 仅保留你指定的键
access_get_control	获取特定控件完整、未经删节的定义块——用于查找 access_list_controls 未返回的属性（可查找 Pages/OptionGroups 中的控件）
access_search_controls	在每个窗体/报表的控件属性中搜索文本或正则表达式（ControlSource、RowSource、Caption、Tag、Filter……或 properties=["all"]）。匹配前会合并跨续行的值
access_create_control	在设计视图中通过 COM 创建新控件。ActiveX 支持通过 class_name 初始化 ProgID（类型 119）。原生 WebBrowser 请使用类型 128（acWebBrowser）
access_delete_control	通过 COM 删除控件
access_set_control_props	在设计视图中通过 COM 修改控件属性
access_set_multiple_controls	在单次设计视图会话中修改多个控件的属性
access_lint_form	对明显有问题的布局进行确定性检查：对比度（WCAG）、重叠、超出边界、文本截断、同级控件不一致、尺寸为零/不可见。返回 verdict，值为 PASS/REVIEW/FAIL。每次编辑控件时也会自动运行

⚠️ 关于 access_lint_form 的说明——请合理调整预期

它不是设计器，也没有任何超强设计能力。 别指望它能让窗体看起来漂亮、推荐好看的配色，或具备审美——它没有，也永远不会有。

它是一个迟钝但确定的验证器，只检查明显且易于检查的问题：文本颜色是否与背景相同？两个控件是否实际重叠？标题是否超出文本框？是否有内容超出窗体边缘，或高度为零像素？仅此而已。就是简单的数学计算——WCAG 对比度和矩形相交检测——再加上一堆防误报机制，避免误报问题。

把它当作安全带，而不是造型师：它不会让汽车变漂亮，只会避免你在没注意的情况下发布一个白底白字的窗体。每次编辑控件时都会自动运行，让这些明显的问题自行显现。如果你期待的是 UI 设计 AI，那它并不是（欢迎提交诚恳的 PR，让它变得更智能 😄）。

文本导出/导入

工具	描述
access_export_text	通过 SaveAsText 将窗体/报表/模块导出为文本。不会打开设计视图。输出为 UTF-16 LE
access_import_text	通过 LoadFromText 从文本导入窗体/报表/模块。若已存在则替换。自动拆分 CodeBehindForm VBA

数据库属性

工具	描述
access_get_db_property	读取数据库属性（CurrentDb.Properties）或 Access 选项（GetOption）
access_set_db_property	设置数据库属性或 Access 选项——若属性不存在则创建
access_get_form_property	读取窗体或报表属性（RecordSource、Caption、DefaultView 等）。必须提供 object_type（form 或 report）。省略 property_names 则读取全部属性。section 用于读取某个节
access_set_form_property	在设计视图中通过 COM 设置窗体/报表属性（RecordSource、Caption、DefaultView、HasModule 等）。section（Detail、FormHeader、0–8 等）用于指定某个节：BackColor、Height、Visible 等

链接表

工具	描述
access_list_linked_tables	列出链接表及其源表、连接字符串和 ODBC 标记。name='X' 返回一个表；names_only=true 提供精简列表（不含连接字符串——当数百个链接导致结果溢出时使用）；mask_password=true 会屏蔽 PWD=
access_relink_table	更改连接字符串并刷新链接——检测到 UID/PWD 时自动保存凭据（dbAttachSavePWD）。relink_all=true 会更新所有使用相同原始连接的表。refresh=true 会使用表自身的连接字符串重新读取架构（不使用 new_connect，不会输出密码）

关系

工具	描述
access_list_relationships	列出表关系及字段映射和级联标记
access_create_relationship	在两个表之间创建关系（支持级联更新/删除）
access_delete_relationship	按名称删除关系

VBA 引用

工具	描述
access_list_references	列出 VBA 项目引用及其 GUID、路径、损坏/内置状态
access_manage_reference	添加（按 GUID 或文件路径）或移除 VBA 引用——防止移除内置引用

维护

工具	描述
access_compact_repair	压缩并修复数据库——关闭数据库、压缩到临时文件、原子替换，然后重新打开
access_decompile_compact	通过 /decompile 移除孤立的 VBA p-code，重新编译，然后压缩。经过大量编辑的前端数据库通常可缩减 60-70%。当不含数据的 .accdb 超过 30-40 MB 时使用

查询管理

工具	描述
access_manage_query	创建、修改、删除、重命名 QueryDef，或读取其 SQL。删除时必须设置 confirm=true

索引

工具	描述
access_list_indexes	列出表的索引及其字段、主键、唯一和外键标记
access_manage_index	创建或删除索引。创建时必须提供字段列表，并可指定排序顺序

VBA 编译

工具	描述
access_vbe_check_syntax	对已打开的 VBA 项目进行静态结构检查——不反编译，不会丢弃任何内容。安全的编辑后检查。它不是编译器：不会解析标识符、类型或引用
access_compile_vba	编译并保存所有 VBA 模块。可选的 timeout 用于自动关闭错误 MsgBox。会先反编译，可能丢弃未保存的 VBA——快速检查请使用 access_vbe_check_syntax

VBA 和宏执行

⚠️ 默认禁用（v0.7.51）。 这三个工具会运行任意代码，并受 MCP_ACCESS_ALLOW_CODE_EXEC 环境变量控制。启用方法请参阅 安全。

工具	描述
access_run_macro	按名称执行 Access 宏
access_run_vba	执行 VBA Sub/Function。标准模块使用 Application.Run，窗体模块使用 Forms.FormName.Method 语法（COM）。可选的 timeout 会自动关闭 MsgBox/InputBox
access_eval_vba	通过 Application.Eval 计算 VBA 表达式。支持域函数、VBA 内置函数、打开的窗体属性和标准模块函数。对于 Eval 无法解析的类实例和其他表达式，会自动回退到临时模块

导出

工具	描述
access_output_report	通过 DoCmd.OutputTo 将报表导出为 PDF、XLSX、RTF 或 TXT

数据传输

工具	描述
access_transfer_data	在 Access 与 Excel（.xlsx）或 CSV 之间导入/导出数据。支持 range（Excel）和 spec_name（CSV）

字段属性

工具	描述
access_get_field_properties	读取表字段的所有属性（DefaultValue、ValidationRule、Description、Format 等）
access_set_field_property	设置字段属性；如果属性不存在，则创建该属性

启动选项

工具	描述
access_list_startup_options	列出 14 个常见启动选项（AppTitle、StartupForm、AllowBypassKey 等）及其当前值

截图与 UI 自动化

工具	描述
access_screenshot	将 Access 窗口截取为 PNG。可选择先打开窗体/报表。返回路径、尺寸（原始尺寸和图像尺寸）及元数据。可配置 max_width（默认值为 1920）、wait_ms（处理 Windows 消息——触发 Timer 事件并初始化 ActiveX）和 open_timeout_sec（默认值为 30——如果 Form_Load 因慢速查询而挂起，则发送 ESC 取消）
access_ui_click	在 Access 窗口的图像坐标处单击。坐标相对于之前的截图（缩放时必须提供 image_width）。支持 left、double 和 right 单击
access_ui_type	输入文本或发送键盘快捷键。普通字符使用 text（WM_CHAR），特殊按键使用 key（enter、tab、escape、f1-f12、箭头键等），组合键使用 modifiers（ctrl、shift、alt）

交叉引用

工具	描述
access_find_usages	一次调用即可在 VBA 代码、查询 SQL 和控件属性（ControlSource、RecordSource、RowSource、SourceObject、DefaultValue、ValidationRule、LinkChildFields、LinkMasterFields）中搜索名称。每个控件匹配项都包含所属控件、完整值及其所在行

知识库

工具	描述
access_tips	按需提供提示和注意事项。主题：eval、controls、gotchas、sql、vbe、compile、design。调用前不消耗令牌

典型工作流

定向编辑 VBA（推荐）

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

完整替换对象（窗体、报表、模块）

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

创建新窗体

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]"})

截图与 UI 交互

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

安全

这是一个本地 stdio 服务，没有网络接口，因此按设计无需登录——完整威胁模型请参阅 SECURITY.md。主要风险是提示词注入：Agent 受到诱骗（通过 db_path 或从数据库读取的内容），进而调用代码执行工具。

默认禁用代码执行（v0.7.51）。 三个可运行任意 VBA/Shell 的工具——access_run_vba、access_eval_vba、access_run_macro——默认隐藏且会被拒绝，除非你通过环境变量选择启用。若要重新启用，请将其添加到 MCP 客户端配置中此服务的 env，然后重启：

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

启用后将允许执行任意 OS 命令；请仅将此服务指向可信数据库。详情及问题报告方式请参阅 SECURITY.md。

环境变量

这三个变量都从服务进程读取，因此应放在 MCP 客户端配置的 env 块中，并在重启后生效。

变量	默认值	作用
MCP_ACCESS_ALLOW_CODE_EXEC	关闭	设置为 1/true/yes/on 以启用 access_run_vba、access_eval_vba 和 access_run_macro。默认拒绝：其他任何值都会使它们保持禁用状态。
MCP_ACCESS_SHIFT_BYPASS	开启	设置为 0/false/no/off，以停止在 OpenCurrentDatabase 和 /decompile 期间按住 SHIFT。默认允许：其他任何值都会保留此绕过行为。
MCP_ACCESS_EXCLUSIVE	关闭	设置为 1/true/yes/on，以独占方式打开会话的数据库。默认拒绝：其他任何值都会保持共享模式。

关于 SHIFT 绕过（v0.7.53）。 按住 SHIFT 是服务跳过数据库 AutoExec 宏和启动窗体的方式，但按下按键是一个全局操作系统事件——它不局限于 Access，因此按住期间，你在计算机上任何位置输入的内容都会变成大写（每次切换数据库约 0.3 秒，每次反编译约 3 秒）。如果这让你困扰，并且你的数据库能自行保护启动流程，就可以关闭此功能；更简洁的修复方式是在数据库中处理：

If Not Application.UserControl Then
  Exit Function
End If

通过 COM 启动 Access 时，Application.UserControl 为 False，因此数据库会在自动化运行时自行选择不启用此行为，完全不需要绕过。关闭绕过后，AutomationSecurity 和对话框监视程序仍然会生效——但未设防的 AutoExec 宏对象仍会运行。

关于独占打开（v0.7.55）。 共享打开是默认行为，也是此前所有版本的行为；它无法获取设计锁。通过 SaveAsText/LoadFromText 附加数据宏，或任何经由 DoCmd.OpenTable acViewDesign 执行的操作，如果有其他 Access 会话打开了相应表，就会被拒绝；每次只针对一个表，且不会停止运行：运行会完成、报告成功，但不会有任何更改。开启此开关后，数据库打开时就会出现一次明确的失败。

默认关闭此开关，因为它确实会启用独占模式：会话会在各次工具调用之间保持数据库打开，因此只要服务保持连接，其他人就无法打开该数据库。这适合构建或开发机器，但不适合共享的前端。access_close 会释放数据库，但不会停止服务。

此开关还会验证模式，而不是盲目信任它。Access 会将 Exclusive:=True 视为请求：如果文件已在使用中，它会默默以共享模式打开；如果其他人已独占该文件，它不会引发错误，却会让会话完全没有数据库。因此，服务会在打开前检查锁文件（拒绝操作且不接触会话），打开后再次检查（如果 Access 降级了模式，就关闭数据库），并在错误中列出持有锁的会话。不会把 Access 崩溃后遗留的过期锁文件误认为有效锁。开启此开关后，服务也会停止附加到已运行的 Access 实例，因为该实例会以共享模式持有文件。

关闭此开关时，仍会收到提示（v0.7.56）。 默认仍为共享模式，不会拒绝任何操作；但如果其他 Access 会话已打开该数据库，服务会在打开数据库的调用结果中说明此情况，并列出持有锁的会话。在这种状态下，设计操作会悄无声息地只完成一部分；而最可能让服务连接到正在使用的前端的人，也最不可能知道这一点。现在，如果数据库被另一个进程独占，服务也会报告锁冲突——Access 会拒绝此次打开但不报错，而此前这会被诊断为 AutoExec 损坏，导致人们去启动代码中排查锁定问题。

备注

• Access 以可见状态运行（Visible = True），确保 VBE COM 访问正常工作。
• 所有工具调用共享一个 Access 实例（单例会话）。打开另一个 .accdb 文件时，之前的实例会关闭。
• COM 线程隔离：所有 COM 调用都在专用的单线程执行器（_com_executor）中运行，并调用 CoInitialize()。这样可确保 COM 在一个 STA 线程中运行，同时让 asyncio 事件循环保持空闲，以处理 stdio I/O，避免出现 -32602 错误。
• 自动重连：如果 COM 会话失效（Access 崩溃、被手动关闭或 COM 损坏），服务会通过健康检查检测到问题，并在下次工具调用时自动重连。
• access_get_code 会从窗体／报表导出内容中移除二进制部分（PrtMip、PrtDevMode 等），access_set_code 会在导入前自动还原这些部分。
• 所有 VBE 行号均从 1 开始计数。

已知限制

• ActiveX 控件（类型 119 = acCustomControl）：access_create_control 现在接受带有 ProgID 的 class_name 参数（例如 Shell.Explorer.2）来初始化 OLE 控件。对于 WebBrowser，请使用类型 128（acWebBrowser），它会创建无需处理 OLE 复杂性的原生控件。通过 COM 设置 ctrl.Class 可能不适用于所有 ActiveX 控件；从功能区手动插入仍是最可靠的方法。
• access_run_vba：现在支持通过 Forms.FormName.Method 语法调用窗体模块过程（直接访问 COM，窗体必须处于打开状态）。也支持 timeout 参数；超时时会自动关闭 MsgBox/InputBox 对话框。如需更灵活地与窗体交互，请使用 access_eval_vba。
• 计时器事件（Form_Timer）：当 wait_ms > 0 时，现在会在 access_screenshot 期间触发；等待循环会通过 pythoncom.PumpWaitingMessages() 处理 Windows 消息。其他工具仍会阻塞消息泵。
• 由于 MCP 传输转义，access_vbe_append 之前会将 & 编码为 &。此问题已在 v0.7.3 中通过显式调用 html.unescape() 解码修复。

故障排除

间歇性出现 -32602 Invalid request parameters 错误

MCP Python SDK（v1.26.0）在 mcp/shared/session.py 中使用了一个会吞掉真实错误并返回无详细信息的通用 -32602 错误代码的 except Exception。本机已应用本地补丁，会在错误响应中包含实际异常和回溯。如果升级 mcp 包，请重新应用该补丁；详情请参阅 CLAUDE.md。

更新日志

完整的发布历史请参阅 CHANGELOG.md。