MS Access MCP Explorer

MS Access MCP Explorer

使用 MCP（Model-Command-Procedure）探索和查询 Microsoft Access 数据库的工具。

安装

使用 UV 安装：

uv pip install omni-ms-access-mcp

或使用 pip：

pip install omni-ms-access-mcp

用法

命令行

指定 Access 数据库的路径，启动 MCP 服务：

ms-access-mcp --db-path "C:\path\to\your\database.accdb"

Python API

from omni_ms_access_mcp.server import AccessMCP

# Initialize the MCP server
mcp_server = AccessMCP(db_path="C:/path/to/your/database.accdb")

# Run the server
mcp_server.run()

可用工具

1. list_databases - 列出所有可用数据库

   • 无需参数
   • 显示所有已注册数据库及其描述

2. get_schema_tool - 获取数据库架构信息

   • 必需参数：database - 要检查的数据库名称
   • 示例：get_schema_tool(database="sales_db")

3. query_data - 跨多个数据库执行 SQL 查询

   • 必需参数：sql - 使用 [database].[table] 语法的 SQL 查询
   • 示例：query_data(sql="SELECT TOP 10 * FROM [sales_db].[Customers]")

4. test_cross_db_connectivity - 测试数据库连接和跨数据库功能

   • 无需参数
   • 帮助诊断连接问题

5. query_builder_help - 获取构建 Access SQL 查询的示例

   • 必需参数：query_type - 所需帮助的查询类型
   • 选项：simple_select、cross_database_join、union、aggregation、date_filtering、boolean_filtering
   • 示例：query_builder_help(query_type="cross_database_join")

6. validate_query_syntax - 执行前验证 Access SQL 语法

   • 必需参数：sql - 要验证的查询
   • 检查常见的 Access SQL 错误

7. query_limitations - 了解 Access 的限制及解决方法

   • 必需参数：topic - 限制主题
   • 选项：joins、performance、data_types、functions、best_practices、all
   • 示例：query_limitations(topic="joins")

跨数据库查询支持

此工具支持使用特殊语法跨多个 Access 数据库查询：

-- Always use [database_name].[table_name] format
SELECT [c].[CustomerName], [o].[OrderTotal]
FROM [sales_db].[Customers] AS [c], [orders_db].[Orders] AS [o]
WHERE [c].[CustomerID] = [o].[CustomerID]
AND [o].[OrderDate] > #2024-01-01#

重要的 Access SQL 规则

• 日期：使用 #YYYY-MM-DD# 格式（不要使用引号）
• 布尔值：使用 1/0，不要使用 True/False
• 字符串拼接：使用 &，不要使用 +
• 限制结果：使用 TOP N，不要使用 LIMIT
• 条件语句：使用 IIF()，不要使用 CASE WHEN

已知限制

跨数据库 JOIN

数据库之间直接 JOIN 通常会失败。请使用以下替代方法：

• 使用 WHERE 子句筛选：FROM [db1].[t1], [db2].[t2] WHERE [t1].[id]=[t2].[id]
• 使用 UNION 操作合并结果
• 分别查询数据库，再在应用代码中合并

性能

• 数据库文件大小限制为 2GB
• 记录数超过 100k 时，查询速度会显著下降
• 始终使用 TOP N 或 WHERE 子句限制结果

数据类型

• 布尔字段可能使用 1/0 或 -1/0
• 文本字段长度限制为 255 个字符（更长的文本请使用 Memo）
• 使用转换函数：CInt()、CDbl()、CStr()、CDate()

最佳实践

1. 所有表始终使用 [database].[table] 语法
2. 先使用小型数据集进行测试
3. 执行复杂查询前使用 validate_query_syntax
4. 运行 query_limitations 工具以了解限制
5. 尽可能将相关数据存储在同一数据库中

故障排除

如果遇到错误：

1. 运行 test_cross_db_connectivity，检查所有数据库是否可访问
2. 使用 get_schema_tool 验证表名和列名
3. 查看 query_builder_help 获取正确语法示例
4. 查看 query_limitations 了解已知问题及解决方法

开发

设置开发环境

uv venv
.venv\Scripts\activate.bat
uv pip install -e .

构建软件包

publish.bat

发布到软件包索引

uv pip install -U twine
uv python -m twine upload dist/*

要求

• 系统必须安装 Microsoft Access Driver
• Python 3.7 或更高版本