Msaccess Vcs MCP

msaccess vcs mcp

一个轻量级的MCP服务器（模型上下文协议服务器），为 MSAccess VCS插件此工具充当桥梁，允许AI助手（例如Cursor、Claude Code和其他MCP兼容客户端）通过版本控制操作与Microsoft Access数据库协同工作。

特性

• 完全出口：导出所有数据库对象（窗体、报表、查询、模块、宏等）
• 快速保存：增量导出（仅更改对象）
• 按对象操作：按名称和类型导出或导入单个对象
• 合并构建：将源更改导入现有数据库
• 从源代码构建：从源文件创建新数据库
• 对象库存：列出Access数据库中的所有对象
• 更改跟踪：将数据库与源文件进行比较
• sql查询：通过外接程序的DAO连接执行只读SELECT查询
• VBA执行：调用现有VBA函数或运行代理生成的代码
• 异步操作：长时间运行的导出/构建通过HTTP回调报告进度
• 加载项选项：在运行时读取和写入VCS插件设置
• 安全护栏：路径验证、权限检查和写禁用模式

建筑

此MCP服务器是 轻质包装材料 围绕MSAccess VCS插件，将所有数据库操作委托给经过实战测试的插件：

AI Agent -> MCP Server (Python) -> VCS Add-in (VBA) -> Access Database
                |
          Path validation
          Permission checks
          Result formatting
          Async progress tracking

所有业务逻辑都存在于VBA中。MCP层验证输入、管理异步生命周期并格式化响应。

先决条件

• python：3.10或更高
• Microsoft Access：安装在Windows上（用于COM自动化）
• pywin32：Python COM接口（自动安装）
• MSAccess VCS插件：必须安装(下载最新版本)

入门指南

跑步最快的方法是 uvx （uv的工具转轮）。无需克隆或虚拟环境。

1.安装uv

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2.安装MSAccess VCS加载项

此MCP服务器需要安装MSAccess VCS加载项。

1. 下载 最新版本 来自GitHub
2. 提取 Version Control.accda 到受信任的位置
3. 打开 Version Control.accda 启动安装程序
4. 点击 安装加载项

该加载项将安装到 %AppData%\MSAccessVCS\Version Control.accda 默认情况下。

3.注册MCP服务器

将服务器条目添加到MCP客户端配置中。Cursor和Claude代码使用相同的 mcpServers 格式，只是在不同的文件中：

将以下内容添加到相应的配置文件中：

{
  "mcpServers": {
    "msaccess-vcs-mcp": {
      "command": "uvx",
      "args": ["msaccess-vcs-mcp@latest"]
    }
  }
}

这 @latest 后缀确保 uvx 始终从中提取最新版本 PyPI 而不是使用缓存副本。

克劳德代码的替代方案 --您可以使用CLI而不是编辑JSON：

claude mcp add msaccess-vcs-mcp -- uvx msaccess-vcs-mcp@latest

4.配置数据库

创建一个 .env 项目根目录中的文件：

# Target database for this project
ACCESS_VCS_DATABASE=C:\Projects\MyApp\database.accdb

# Optional: Disable database writes for safety
# ACCESS_VCS_DISABLE_WRITES=true

# Optional: Custom add-in path
# ACCESS_VCS_ADDIN_PATH=C:\Custom\Path\Version Control.accda

5.重新启动客户端

关闭并重新打开Cursor或Claude Code。MCP服务器将被自动检测和加载。

6.试试看

请AI助手使用VCS工具：

“使用vcs_List_objects列出我的Access数据库中的所有对象”

“使用vcs_Export_database将我的Access数据库导出到src文件夹”

“使用vcs_diff_database将我的数据库与源文件进行比较”

配置

所有配置都是通过环境变量完成的，通常在 .env 项目根目录中的文件。服务器加载 .env 启动时自动。

环境变量

项目特定配置

此工具支持按项目配置，使用 .env 文件夹：

.env （Gitigned，项目特定）

存储项目特定的数据库路径：

ACCESS_VCS_DATABASE=C:\Projects\MyApp\database.accdb

.env.local （可选，Gitigned）

对于不应影响团队的个人覆盖：

ACCESS_VCS_DATABASE=C:\Users\YourName\dev\testdb.accdb

环境变量优先级

1. MCP服务器 env 部分 （最高优先级）--在MCP配置文件中设置的值
2. .env.local --个人优先权
3. .env --项目特定配置（最低优先级）

使用来自另一个项目的msaccess vcs-mcp

当服务器在用户级别安装一次时（在 ~/.cursor/mcp.json 而不是每个项目），它仍然需要找到每个单独项目的 .env 因此，设置如下 ACCESS_VCS_DATABASE 和 ACCESS_VCS_ENABLE_LOGGING 生效。服务器按以下顺序解析项目根：

1. ACCESS_VCS_PROJECT_DIR --显式覆盖，在MCP中设置 env 如果需要的话。
2. MCP工作区根 --当客户端（Cursor、VS Code、Claude Code等）支持 roots/list，服务器在第一次工具调用时懒洋洋地发现工作区并加载 .env 无需配置。
3. 从工作目录向上搜索 --当IDE以工作区启动服务器时，会自动工作 cwd （典型案例）。
4. 从已安装的软件包位置向上搜索 --开发安装的最后手段。

.env 文件也会被热重新加载：编辑 .env 当服务器运行时，会导致下一个工具调用获取新值，包括 ACCESS_VCS_ENABLE_LOGGING.

服务器在启动时将诊断打印到stderr（在Cursor的MCP服务器输出窗格中可见），显示已解析的项目根目录和已加载的文件——如果设置未生效，请先检查那里。

可用工具

数据库级操作

vcs_export_database(database_path, output_dir, object_types, full_export)

通过VCS加载项将Access数据库对象导出到源文件。

支持所有Access对象类型：表、查询、窗体、报表、模块、宏等。默认情况下使用快速保存（仅导出更改的对象）。长时间运行的导出通过异步回调报告进度。

Args：

• database_path：Access数据库的路径（.accdb、.accda、.mdb）
• output_dir：将源文件导出到的目录
• object_types：可选类型列表（默认为所有类型）
• full_export：如果为True，则导出所有对象（而不仅仅是更改的对象）

退货： success, exported_count, export_path, objects_by_type, log_path

vcs_export_database("C:\\db.accdb", "C:\\src\\mydb")

vcs_export_database("C:\\db.accdb", "C:\\src\\mydb", object_types=["modules"])

vcs_list_objects(database_path)

按类型列出Access数据库中的所有对象。

Args：

• database_path：Access数据库的路径

退货： tables, queries, modules （以及 forms, reports 未来）

vcs_list_objects("C:\\db.accdb")

vcs_diff_database(database_path, source_dir, show_details)

将数据库对象与源文件进行比较，看看发生了什么变化。

Args：

• database_path：Access数据库的路径
• source_dir：包含源文件的目录
• show_details：如果为True，则显示详细的差异

退货： queries, modules, new_in_db, new_in_source

vcs_diff_database("C:\\db.accdb", "C:\\src\\mydb")

vcs_import_objects(database_path, source_dir, object_types, overwrite)

使用合并生成将对象从源文件导入Access数据库。

将源文件更改合并到现有数据库中，而不需要完全重建。需要写入权限。

Args：

• database_path：Access数据库的路径
• source_dir：包含源文件的目录
• object_types：要导入的可选类型列表
• overwrite：如果为True，则覆盖现有对象

vcs_import_objects("C:\\db.accdb", "C:\\src\\mydb")

vcs_rebuild_database(source_dir, output_path, template_path)

从源文件构建完整的Access数据库。

从源文件创建一个新的数据库，这对于干净的构建和分发非常有用。需要写入权限。

Args：

• source_dir：包含源文件的目录
• output_path：新数据库文件的路径
• template_path：用作起点的可选模板数据库

vcs_rebuild_database("C:\\src\\mydb", "C:\\output\\fresh.accdb")

按对象操作

vcs_export_object(database_path, object_type, object_name)

将单个命名数据库对象导出到其源文件。当您只需要刷新一个对象时，比完整数据库导出快得多。

Args：

• database_path：Access数据库的路径
• object_type：对象类型： "query", "form", "report", "module", "table", "macro"
• object_name：要导出的对象的名称

vcs_export_object("C:\\db.accdb", "query", "qryCustomers")
vcs_export_object("C:\\db.accdb", "module", "modUtils")

vcs_import_object(database_path, object_type, object_name)

将源文件中的单个命名对象导入数据库。源文件必须存在于项目的导出文件夹中。需要写入权限。

Args：

• database_path：Access数据库的路径
• object_type：对象类型： "query", "form", "report", "module", "table", "macro"
• object_name：要导入的对象的名称

vcs_import_object("C:\\db.accdb", "query", "qryCustomers")
vcs_import_object("C:\\db.accdb", "module", "modUtils")

SQL和VBA执行

vcs_execute_sql(database_path, sql, max_rows)

通过外接程序的DAO连接对数据库执行只读SELECT查询。

只允许使用SELECT语句——INSERT、UPDATE、DELETE和DDL被拒绝。使用外接程序已持有的相同数据库连接，避免文件锁定冲突。

Args：

• database_path：Access数据库的路径
• sql：要执行的SELECT语句
• max_rows：要返回的最大行数（默认值：100）

退货： rows, rowCount, truncated

vcs_execute_sql("C:\\db.accdb", "SELECT Name, Type FROM MSysObjects WHERE Type=5")
vcs_execute_sql("C:\\db.accdb", "SELECT * FROM Customers", max_rows=50)

vcs_call_vba(database_path, function_name, args)

通过以下方式按名称调用现有的公共VBA函数 Application.Run重量比 vcs_run_vba 因为没有临时模块创建或编译步骤。

Args：

• database_path：Access数据库的路径
• function_name：完全限定的函数名称（例如。， "ModuleName.FunctionName")
• args：可选字符串参数列表（最多3个）

vcs_call_vba("C:\\db.accdb", "MyModule.GetQuerySQL", ["qryCustomers"])
vcs_call_vba("C:\\db.accdb", "Version Control.API", ["GetVCSVersion"])

vcs_run_vba(database_path, code)

在临时模块中执行代理生成的VBA代码。

该插件处理整个生命周期：创建一个临时模块，将代码封装在一个具有错误处理功能的函数中，编译项目以进行验证，执行，捕获结果，删除临时模块，并返回结构化JSON。

需要 McpAllowRunVBA 要启用的选项 （默认设置：关闭）。用户必须在VCS选项窗体中手动启用此选项——代理无法以编程方式设置此选项。

Args：

• database_path：Access数据库的路径
• code：要执行的VBA代码块

vcs_run_vba("C:\\db.accdb", "MCP_TempFunction = CurrentDb.TableDefs.Count")

VBA编译

vcs_check_vba_compiled(database_path)

检查Access数据库中的VBA代码是否已编译。返回编译状态，而不尝试编译。有助于在更改代码之前建立基线。

Args：

• database_path：Access数据库的路径

退货： success, compiled

result = vcs_check_vba_compiled("C:\\db.accdb")
# result["compiled"] -> True or False

vcs_compile_vba(database_path, suppress_warnings)

编译Access数据库中的所有VBA模块并返回成功状态。

如果编译失败，请不要继续进行代码编辑，因为存在必须首先修复的现有编译错误。

Args：

• database_path：Access数据库的路径
• suppress_warnings：如果为True，则在编译过程中抑制消息框

退货： success

result = vcs_compile_vba("C:\\db.accdb", suppress_warnings=True)

加载项选项

vcs_set_option(database_path, option_name, value)

为当前会话设置VCS加载项选项。

更改立即生效，但不会持续到 vcs-options.json 直到明确保存。

Args：

• database_path：Access数据库的路径
• option_name：VCS选项属性的名称
• value：要设置的值（字符串、布尔值或整数）

vcs_set_option("C:\\db.accdb", "ShowDebug", True)

vcs_get_option(database_path, option_name)

读取VCS插件选项值。

Args：

• database_path：Access数据库的路径
• option_name：要读取的VCS选项属性的名称

vcs_get_option("C:\\db.accdb", "ShowDebug")
vcs_get_option("C:\\db.accdb", "McpAllowRunVBA")

诊断

vcs_get_version_info()

获取MCP服务器、MSAccess VCS加载项和Access应用程序的版本信息。

退货 mcp_version, vcs_version, access_version, bitness, target_database, addin_path, callback_url, async_available，以及任何 errors 或 warnings.

vcs_get_version_info()

vcs_cancel_operation(operation_id)

取消正在运行的异步操作。请求取消长时间运行的导出、生成或导入。VBA加载项将在其下一个DoEvents周期中检测到取消。

Args：

• operation_id：要取消的操作的UUID（由异步工具调用返回）

vcs_cancel_operation("a1b2c3d4-5678-90ab-cdef-1234567890ab")

vcs_get_log(database_path, log_type)

从源文件夹的logs目录读取最新的操作日志文件。

Args：

• database_path：Access数据库的路径
• log_type：要读取的日志类型： "Export" （默认）或 "Build"

vcs_get_log("C:\\db.accdb")
vcs_get_log("C:\\db.accdb", log_type="Build")

异步操作

长时间运行的操作（导出、导入、重建）支持异步执行和进度报告。当回调服务器运行时（默认启用），这些操作：

1. 通过外接程序生成分离的VBA进程 APIAsync 入口点
2. 立即返回 operation_id
3. 通过VBA的HTTP回调接收进度更新
4. 支持通过以下方式取消 vcs_cancel_operation

服务器会自动检测同一数据库何时正在进行另一个操作，并返回一个包含活动操作详细信息的忙碌响应。

如果回调服务器不可用，操作将回退到同步执行。

看 docs/VBA_CALLBACK_API.md文件 以获取完整的回调协议规范。

导出格式

VCS插件将数据库对象导出到一个包含文本文件的综合文件夹结构中。请参阅 代理商.md 完整格式文档指南。

示例结构

database.src/
├── queries/           # SQL queries (.sql, .bas)
├── modules/           # VBA modules (.bas, .cls)
├── forms/             # Form definitions (.bas, .cls)
├── reports/           # Report definitions (.bas, .cls)
├── macros/            # Macros (.bas)
├── tables/            # Table data (.txt, .xml)
├── tbldefs/           # Table structure (.sql, .xml)
├── vcs-options.json   # Export options
├── vcs-index.json     # Fast save index
└── Export.log         # Operation log

所有文件使用 UTF-8与BOM 编码，这对于正确导入回Access至关重要。

工作流

版本控制工作流

# 1. Export database to source
vcs_export_database("C:\\db.accdb", "C:\\src\\db")

# 2. Initialize git (if not already done)
# cd C:\src\db && git init && git add . && git commit -m "Initial export"

# 3. Make changes in Access...

# 4. See what changed
vcs_diff_database("C:\\db.accdb", "C:\\src\\db")

# 5. Export changes
vcs_export_database("C:\\db.accdb", "C:\\src\\db")

# 6. Commit changes
# git add . && git commit -m "Updated customer queries"

按对象开发工作流

# 1. Edit a VBA module in source files...

# 2. Import just that module
vcs_import_object("C:\\db.accdb", "module", "modUtils")

# 3. Compile to validate
vcs_compile_vba("C:\\db.accdb")

# 4. Test via VBA
vcs_call_vba("C:\\db.accdb", "modUtils.RunTests")

# 5. Export the module back (picks up any Access-side formatting)
vcs_export_object("C:\\db.accdb", "module", "modUtils")

与db检查器mcp集成

这两种工具协同工作，实现全面的数据库工作流程：

# 1. Analyze database structure (db-inspector-mcp)
db_list_tables(database="legacy")
db_list_views(database="legacy")

# 2. Export to version control (msaccess-vcs-mcp)
vcs_export_database("C:\\legacy.accdb", "C:\\src\\legacy-db")

# 3. Run queries against the database (msaccess-vcs-mcp)
vcs_execute_sql("C:\\legacy.accdb", "SELECT * FROM Customers WHERE Active = True")

# 4. Cross-database comparison (db-inspector-mcp)
db_compare_queries(
    "SELECT * FROM Customers",
    "SELECT * FROM Customers",
    database1="legacy",
    database2="new"
)

MCP客户端设置

光标

项目级别 --添加 .cursor/mcp.json 到您的项目根目录（可以进行版本控制以供团队共享）：

{
  "mcpServers": {
    "msaccess-vcs-mcp": {
      "command": "uvx",
      "args": ["msaccess-vcs-mcp@latest"]
    }
  }
}

用户级别 --添加到 ~/.cursor/mcp.json 使服务器在所有项目中都可用。

克劳德代码

项目级别 --添加 .mcp.json 到您的项目根目录：

{
  "mcpServers": {
    "msaccess-vcs-mcp": {
      "command": "uvx",
      "args": ["msaccess-vcs-mcp@latest"]
    }
  }
}

CLI替代方案 --注册而不编辑JSON：

claude mcp add msaccess-vcs-mcp -- uvx msaccess-vcs-mcp@latest

开发安装

对于贡献或从源代码运行：

git clone https://github.com/joyfullservice/msaccess-vcs-mcp.git
cd msaccess-vcs-mcp
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux
pip install -e ".[dev]"

对于开发安装，请使用 python -m msaccess_vcs_mcp.main 如MCP配置中的命令：

{
  "mcpServers": {
    "msaccess-vcs-mcp": {
      "command": "python",
      "args": ["-m", "msaccess_vcs_mcp.main"]
    }
  }
}

故障排除

如果MCP服务器未加载：

1. 检查MCP日志 --在光标中，打开命令选项板(Ctrl+Shift+P)并寻找与MCP相关的输出。在Claude Code中，检查终端输出。

1. 验证命令是否有效 --奔跑 uvx msaccess-vcs-mcp --help 在你的终端。

1. 检查你的 .env 文件 --确保它位于项目根目录中，数据库路径正确，并且没有语法错误。

安全模型

写入操作

数据库写入操作（导入、重建、运行VBA）包括 默认启用.为防止修改：

ACCESS_VCS_DISABLE_WRITES=true

VBA执行权限

VBA执行有两层，通过外接程序选项控制单独的权限：

• vcs_call_vba：通过调用现有的命名函数 Application.Run.受控于 McpAllowCallVBA （默认值：True）。
• vcs_run_vba：通过临时模块执行代理生成的代码。被控制 McpAllowRunVBA （默认值：False）。必须由用户在VCS选项窗体中明确启用--代理无法通过编程方式启用此选项 vcs_set_option.

路径验证

所有文件路径都经过验证，以防止：

• 访问系统目录
• 文件扩展名无效
• 不存在的路径（除非创建）

代码执行审计跟踪

启用使用记录时(ACCESS_VCS_ENABLE_LOGGING=true)，每一个电话 vcs_execute_sql, vcs_call_vba，或 vcs_run_vba 写a "code_execution" 事件 之前 代码运行。此条目保留了目标数据库路径旁边的完整、未截断的SQL或VBA文本，即使进程在执行过程中崩溃，也能提供取证记录。

// Example log entry (written before execution)
{
  "event": "code_execution",
  "tool": "vcs_execute_sql",
  "database": "C:\\Projects\\mydb.accdb",
  "code_type": "sql",
  "code": "SELECT * FROM Customers WHERE Active = True",
  "timestamp": "2026-04-15T18:30:00+00:00",
  "version": "0.1.0"
}

标准执行后 "tool_call" 事件之后是成功/错误状态和时间。

安全工作流程

为了安全起见，使用生产数据库时：

1. 集 ACCESS_VCS_DISABLE_WRITES=true 生产中
2. 使用导出操作查看更改
3. 仅在准备合并更改时启用写入

发展

运行测试

测试必须在项目虚拟环境中运行：

# Activate the virtual environment first
.\venv\Scripts\Activate.ps1          # Windows PowerShell
# source venv/bin/activate           # macOS/Linux

# Run all tests
pytest

# Run with coverage report
pytest --cov=msaccess_vcs_mcp --cov-report=html

# Skip integration tests (require Access installed)
pytest -m "not integration"

项目结构

msaccess-vcs-mcp/
├── src/
│   └── msaccess_vcs_mcp/
│       ├── __init__.py
│       ├── main.py              # MCP server entry point
│       ├── tools.py             # MCP tool definitions (17 tools)
│       ├── config.py            # Configuration management
│       ├── usage_logging.py     # Structured JSONL usage logging
│       ├── security.py          # Path validation & safety
│       ├── validation.py        # Component validation
│       ├── addin_integration.py # VCS add-in integration
│       ├── operation_manager.py # Async operation tracking
│       ├── callback_server.py   # HTTP callback server
│       └── access_com/
│           ├── connection.py    # COM connection management
│           └── dao_helpers.py   # DAO utility functions
├── tests/                       # Test suite
└── docs/                        # Documentation
    ├── AGENT_WORKFLOWS.md       # AI agent usage patterns
    ├── VBA_INTEGRATION.md       # Add-in integration details
    ├── VBA_CALLBACK_API.md      # Async callback protocol
    ├── EXPORT_FORMATS.md        # Export format reference
    └── TESTING.md               # Testing guide

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请打开问题或提交拉取请求。

相关工具

• db检查员mcp：用于自检和迁移验证的跨数据库MCP服务器
• MSAccess VCS插件：为所有导出/导入操作提供动力的VBA加载项