mcp-msaccess

mcp-access

Da a cualquier asistente de IA control total sobre bases de datos de Microsoft Access.

Crea formularios, escribe VBA, diseña tablas, gestiona controles, ejecuta consultas, construye relaciones y edita cada rincón de una .accdb — todo a través de lenguaje natural. 68 herramientas que convierten Access en algo con lo que puedes hablar.

No se requiere experiencia en Access. Solo describe lo que quieres.

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

La IA se encarga de la automatización COM, la vista de diseño, los módulos VBA, las secciones binarias, la invalidación de caché y todas las partes complicadas. Tú obtienes el resultado.

Lo que puede hacer

• Formularios e informes — crear, clonar, exportar, importar, capturar pantalla, hacer clic, escribir. Ciclo completo de automatización de UI
• VBA — leer, escribir, reemplazar, compilar y ejecutar procedimientos. Edición a nivel de línea o de procedimiento completo
• Controles — crear, eliminar, modificar, listar, establecer orden de pestañas. Encuentra controles anidados dentro de páginas de TabControl
• Tablas y SQL — crear mediante DAO, alterar, consultar, ejecutar en lote, búsqueda de texto completo en todos los campos Texto/Memo. Se admiten tablas ODBC vinculadas
• Relaciones, índices, referencias, consultas, macros — CRUD completo. Clona cualquier objeto (formulario / informe / módulo / clase / consulta / macro) conservando las secciones VBA y binarias
• Mantenimiento — compactar y reparar, descompilar bases de datos infladas, exportar documentos de estructura. Instalación de Office autodetectada (sin más rutas codificadas de Office 16)
• Lint de UI — access_lint_form marca diseños objetivamente rotos (texto blanco sobre blanco, superposiciones, truncamiento, controles fuera del lienzo). Un verificador, no un diseñador — ver la nota más abajo

Funciona con Claude Code, Cursor, Windsurf, Continue o cualquier cliente compatible con MCP.

---

Requisitos

• Windows (la automatización COM es solo para Windows)
• Microsoft Access instalado (cualquier versión que admita VBE, 2010+)
• Python 3.9+
• "Confiar en el acceso al modelo de objetos del proyecto VBA" habilitado en el Centro de confianza de Access

Instalación

pip install mcp pywin32

Habilitar el acceso al modelo de objetos VBA

File → Options → Trust Center → Trust Center Settings → Macro Settings → marcar Confiar en el acceso al modelo de objetos del proyecto VBA

O ejecuta el script de PowerShell incluido:

.\enable_vba_trust.ps1

Registrar con Claude Code

Global (disponible en todos los proyectos):

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

Solo proyecto (crea .mcp.json en el directorio actual):

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

Registrar con otros clientes MCP

Añade a tu archivo de configuración MCP (.mcp.json, mcp.json o configuraciones específicas del cliente):

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

Compatible con cualquier cliente que cumpla con MCP (Cursor, Windsurf, Continue, etc.).

Herramientas (68)

Base de datos

Herramienta	Descripción
access_create_database	Crear un nuevo archivo de base de datos .accdb vacío
access_close	Cerrar la sesión COM y liberar el archivo .accdb

Objetos de base de datos

Herramienta	Descripción
access_list_objects	Listar objetos por tipo (table, module, form, report, query, macro, all). Tablas de sistema filtradas
access_get_code	Exportar la definición completa de un objeto como texto
access_set_code	Importar texto modificado de vuelta (crea o sobrescribe)
access_export_structure	Generar un índice Markdown de todos los módulos, formularios, informes y consultas
access_delete_object	Eliminar un módulo, formulario, informe, consulta o macro. Requiere confirm=true
access_create_form	Crear un nuevo formulario sin activar el MsgBox "Guardar como" que bloquea COM. Opcional has_header para la sección de encabezado/pie, record_source (vincular a tabla/consulta), default_view (0=Individual, 1=Continuo, 2=Hoja de datos, ...)

SQL y tablas

Herramienta	Descripción
access_execute_sql	Ejecutar SQL mediante DAO — SELECT devuelve filas como JSON (limit predeterminado 500). DELETE/DROP/ALTER requieren confirm_destructive=true
access_execute_batch	Ejecutar múltiples sentencias SQL en una sola llamada. Admite SELECT/INSERT/UPDATE/DELETE mixtos con resultados por sentencia, stop_on_error y confirm_destructive
access_table_info	Mostrar la estructura de la tabla mediante DAO (campos, tipos, tamaños, obligatorios, estado de vinculación)
access_search_queries	Buscar texto en el SQL de TODAS las consultas a la vez (encontrar qué consultas hacen referencia a una tabla, campo o palabra clave)
access_create_table	Crear una tabla mediante DAO con soporte completo de tipo, valor predeterminado, descripción y clave primaria en una sola llamada. Más robusto que CREATE TABLE SQL
access_alter_table	Modificar la estructura de la tabla mediante DAO: agregar campo, eliminar campo (requiere confirm=true), renombrar campo

Edición a nivel de línea VBE

Herramienta	Descripción
access_vbe_get_lines	Leer un rango de líneas de un módulo VBA sin exportar todo el archivo
access_vbe_get_proc	Obtener el código y la posición de un procedimiento por nombre
access_vbe_module_info	Listar todos los procedimientos con sus números de línea
access_vbe_replace_lines	Reemplazar/insertar/eliminar líneas en un módulo VBA directamente a través de VBE
access_vbe_find	Buscar texto en UN módulo específico. Para buscar en todos los módulos a la vez, usa access_vbe_search_all
access_vbe_search_all	Buscar texto en TODOS los módulos/formularios/informes de la base de datos a la vez
access_vbe_replace_proc	Reemplazar un procedimiento completo por nombre (calcula automáticamente los límites de línea). Elimina líneas Option mal colocadas, ejecuta verificación estructural de salud
access_vbe_patch_proc	Búsqueda/ reemplazo quirúrgico dentro de un procedimiento. Atómico por defecto (una corrección fallida no escribe nada), anclas insensibles a mayúsculas, require_unique opcional, coincidencia de respaldo tolerante a espacios en blanco + mensajes de error contextuales cuando fallan las correcciones. proc_name='(Declarations)' apunta a la sección de declaraciones
access_vbe_append	Agregar código al final de un módulo. Elimina automáticamente Option Explicit/Option Compare para evitar colocación incorrecta

Controles de formularios e informes

Herramienta	Descripción
access_list_controls	Listar todos los controles de un formulario/informe con propiedades clave. Los controles dentro de Pages/OptionGroups incluyen un campo parent
access_get_control	Obtener el bloque de definición completo de un control específico (encuentra controles dentro de Pages/OptionGroups)
access_create_control	Crear un nuevo control mediante COM en vista de diseño. Soporta class_name para inicialización de ProgID de ActiveX (tipo 119). Usa tipo 128 (acWebBrowser) para WebBrowser nativo
access_delete_control	Eliminar un control mediante COM
access_set_control_props	Modificar propiedades de controles mediante COM en vista de diseño
access_set_multiple_controls	Modificar propiedades de múltiples controles en una sola sesión de vista de diseño
access_lint_form	Verificación determinista de diseños objetivamente rotos: contraste (WCAG), superposición, fuera de límites, truncamiento, inconsistencia entre hermanos, tamaño cero/invisible. Devuelve verdict PASS/REVIEW/FAIL. También se ejecuta automáticamente en cada edición de control

⚠️ Nota sobre access_lint_form — gestiona tus expectativas

Esto NO es un diseñador y no hay ningún super-diseño aquí. No esperes que haga que un formulario se vea bien, sugiera una paleta agradable o tenga algún gusto — no lo tiene y nunca lo tendrá.

Es un verificador tonto y determinista de lo obvio y fácil de comprobar: ¿el texto tiene el mismo color que el fondo? ¿dos controles se superponen físicamente? ¿un título no cabe en su cuadro? ¿algo está fuera del borde del formulario, o tiene cero píxeles de altura? Eso es todo. Matemáticas simples — ratios de contraste WCAG e intersección de rectángulos — con un montón de salvaguardas contra falsos positivos para que no grite lobo.

Piensa en cinturón de seguridad, no en estilista: no hará el coche bonito, solo evita que envíes un formulario con texto blanco sobre fondo blanco sin darte cuenta. Se ejecuta automáticamente en cada edición de control para que esos errores obvios salgan a la luz por sí solos. Si esperabas una IA de diseño de UI, esto no es eso (PRs honestas para hacerlo más inteligente son muy bienvenidas 😄).

Exportar/importar texto

Herramienta	Descripción
access_export_text	Exportar formulario/informe/módulo como texto mediante SaveAsText. NO abre la vista de diseño. Salida UTF-16 LE
access_import_text	Importar formulario/informe/módulo desde texto mediante LoadFromText. Reemplaza si existe. Divide automáticamente el VBA de CodeBehindForm

Propiedades de la base de datos

Herramienta	Descripción
access_get_db_property	Leer una propiedad de DB (CurrentDb.Properties) o una opción de Access (GetOption)
access_set_db_property	Establecer una propiedad de DB o una opción de Access — crea la propiedad si no existe
access_get_form_property	Leer propiedades de formulario o informe (RecordSource, Caption, DefaultView, etc.). Se requiere object_type (form o report). Omite property_names para todas
access_set_form_property	Establecer propiedades de formulario/informe (RecordSource, Caption, DefaultView, HasModule, etc.) mediante COM en vista de diseño

Tablas vinculadas

Herramienta	Descripción
access_list_linked_tables	Listar tablas vinculadas con tabla de origen, cadena de conexión, indicador ODBC. name='X' devuelve una tabla; names_only=true es un listado ligero (sin cadenas de conexión — úsalo cuando cientos de enlaces desborden el resultado); mask_password=true enmascara PWD=
access_relink_table	Cambiar la cadena de conexión y actualizar el vínculo — guarda automáticamente las credenciales (dbAttachSavePWD) cuando se detectan UID/PWD. relink_all=true actualiza todas las tablas con la misma conexión original. refresh=true relee el esquema usando la propia cadena de conexión de la tabla (sin new_connect, la contraseña nunca se muestra)

Relaciones

Herramienta	Descripción
access_list_relationships	Listar relaciones de tablas con mapeos de campos y banderas de cascada
access_create_relationship	Crear una relación entre dos tablas (soporta actualización/eliminación en cascada)
access_delete_relationship	Eliminar una relación por nombre

Referencias VBA

Herramienta	Descripción
access_list_references	Listar referencias del proyecto VBA con GUID, ruta, estado roto/incorporado
access_manage_reference	Agregar (por GUID o ruta de archivo) o eliminar una referencia VBA — protege contra la eliminación de referencias incorporadas

Mantenimiento

Herramienta	Descripción
access_compact_repair	Compactar y reparar la base de datos — cierra, compacta a un temporal, intercambia atómicamente, reabre
access_decompile_compact	Eliminar p-código VBA huérfano mediante /decompile, recompilar y luego compactar. Reducción típica: 60-70% en bases de datos front-end muy editadas. Úsalo cuando un .accdb sin datos supere los 30-40 MB

Gestión de consultas

Herramienta	Descripción
access_manage_query	Crear, modificar, eliminar, renombrar o leer el SQL de un QueryDef. Eliminar requiere confirm=true

Índices

Herramienta	Descripción
access_list_indexes	Listar índices de una tabla con campos, primario, único, banderas extranjeras
access_manage_index	Crear o eliminar un índice. Crear requiere lista de campos con orden de clasificación opcional

Compilación VBA

Herramienta	Descripción
access_vbe_check_syntax	Verificación estructural estática del proyecto VBA ya abierto — sin descompilar, nada se descarta. La verificación segura posterior a la edición. No es un compilador: no resuelve identificadores, tipos ni referencias
access_compile_vba	Compilar y guardar todos los módulos VBA. Opcional timeout para descartar automáticamente el MsgBox de error. Primero descompila y puede descartar VBA no guardado — para una verificación rápida usa access_vbe_check_syntax

Ejecución de VBA y macros

⚠️ Deshabilitado por defecto (v0.7.51). Estas tres herramientas ejecutan código arbitrario y están controladas por la variable de entorno MCP_ACCESS_ALLOW_CODE_EXEC. Consulta Seguridad para habilitarlas.

Herramienta	Descripción
access_run_macro	Ejecutar una macro de Access por nombre
access_run_vba	Ejecutar una Sub/Función VBA. Módulos estándar mediante Application.Run, módulos de formulario mediante sintaxis Forms.FormName.Method (COM). Opcional timeout descarta automáticamente MsgBox/InputBox
access_eval_vba	Evaluar una expresión VBA mediante Application.Eval. Funciones de dominio, funciones integradas de VBA, propiedades de formularios abiertos, funciones de módulos estándar. Recurso automático mediante módulo temporal para instancias de clases y otras expresiones que Eval no puede resolver

Exportación

Herramienta	Descripción
access_output_report	Exportar un informe a PDF, XLSX, RTF o TXT mediante DoCmd.OutputTo

Transferencia de datos

Herramienta	Descripción
access_transfer_data	Importa/exporta datos entre Access y Excel (.xlsx) o CSV. Admite rango (Excel) y spec_name (CSV)

Propiedades de campo

Herramienta	Descripción
access_get_field_properties	Lee todas las propiedades de un campo de tabla (DefaultValue, ValidationRule, Description, Format, etc.)
access_set_field_property	Establece una propiedad de campo: crea la propiedad si no existe

Opciones de inicio

Herramienta	Descripción
access_list_startup_options	Lista 14 opciones de inicio comunes (AppTitle, StartupForm, AllowBypassKey, etc.) con sus valores actuales

Captura de pantalla y automatización de interfaz de usuario

Herramienta	Descripción
access_screenshot	Captura la ventana de Access como PNG. Opcionalmente abre un formulario/informe primero. Devuelve la ruta, las dimensiones (original + imagen) y los metadatos. Configurable max_width (por defecto 1920), wait_ms (bombea mensajes de Windows — los eventos Timer se disparan, ActiveX se inicializa) y open_timeout_sec (por defecto 30 — envía ESC para cancelar si Form_Load se bloquea en una consulta lenta)
access_ui_click	Hace clic en coordenadas de imagen sobre la ventana de Access. Las coordenadas son relativas a una captura anterior (image_width requerido para el escalado). Admite clic left, double y right
access_ui_type	Escribe texto o envía atajos de teclado. text para caracteres normales (WM_CHAR), key para teclas especiales (enter, tab, escape, f1-f12, flechas, etc.), modifiers para combinaciones (ctrl, shift, alt)

Referencia cruzada

Herramienta	Descripción
access_find_usages	Busca un nombre en código VBA, SQL de consultas y propiedades de controles (ControlSource, RecordSource, RowSource, SourceObject, DefaultValue, ValidationRule, LinkChildFields, LinkMasterFields) en una sola llamada

Base de conocimientos

Herramienta	Descripción
access_tips	Consejos y advertencias bajo demanda. Temas: eval, controls, gotchas, sql, vbe, compile, design. Cero tokens hasta que se llaman

Flujos de trabajo típicos

Edición VBA dirigida (recomendada)

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

Reemplazo completo de objetos (formularios, informes, módulos)

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

Crear un nuevo formulario

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

Captura de pantalla e interacción con la interfaz de usuario

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

Seguridad

Este es un servidor stdio local sin superficie de red, por lo que no hay inicio de sesión por diseño: consulte SECURITY.md para el modelo de amenazas completo. El riesgo principal es la inyección de promt: un agente engañado (a través de db_path o contenido que lee de la base de datos) para llamar a una herramienta de ejecución de código.

La ejecución de código está deshabilitada por defecto (v0.7.51). Las tres herramientas que ejecutan VBA/Shell arbitrario — access_run_vba, access_eval_vba, access_run_macro — están ocultas y rechazadas a menos que opte por habilitarlas con una variable de entorno. Para rehabilitarlas, añádala al env de este servidor en la configuración de su cliente MCP y reinicie:

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

Habilitar esto otorga ejecución de comandos arbitrarios del sistema operativo; solo apunte el servidor a bases de datos confiables. Consulte SECURITY.md para obtener detalles y cómo informar problemas.

Variables de entorno

Ambas se leen desde el proceso del servidor, por lo que van en el bloque env de la configuración de su cliente MCP y se aplican al reiniciar.

Variable	Valor por defecto	Efecto
MCP_ACCESS_ALLOW_CODE_EXEC	off	Configúrela a 1/true/yes/on para habilitar access_run_vba, access_eval_vba y access_run_macro. Falla cerrada: cualquier otro valor las mantiene deshabilitadas.
MCP_ACCESS_SHIFT_BYPASS	on	Configúrela a 0/false/no/off para dejar de mantener SHIFT durante OpenCurrentDatabase y /decompile. Falla abierta: cualquier otro valor mantiene la omisión.

Acerca de la omisión por SHIFT (v0.7.53). Mantener SHIFT es la forma en que el servidor omite la macro AutoExec de una base de datos y el formulario de inicio, pero la pulsación de tecla es un evento global del OS — no está limitada a Access, por lo que cualquier cosa que escriba en cualquier lugar de la máquina mientras se mantiene llega en mayúsculas (~0,3 s en cada cambio de base de datos, ~3 s por descompilación). Desactívelo si eso le molesta y sus bases de datos protegen su propio inicio, que es la solución más limpia y pertenece a la base de datos:

If Not Application.UserControl Then
  Exit Function
End If

Application.UserControl es False cuando Access se inició vía COM, por lo que la base de datos se excluye automáticamente bajo automatización y no necesita ninguna omisión. Con la omisión desactivada, AutomationSecurity y el vigilante de diálogos aún se aplican — pero una macro AutoExec objeto sin proteger se ejecutará.

Notas

• Access se ejecuta visible (Visible = True) para que el acceso COM a VBE funcione correctamente.
• Se comparte una única instancia de Access en todas las llamadas a herramientas (sesión singleton). Abrir un .accdb diferente cierra el anterior.
• Aislamiento de hilo COM: Todas las llamadas COM se ejecutan en un ejecutor dedicado de un solo hilo (_com_executor) con CoInitialize(). Esto mantiene COM en un solo hilo STA mientras que el bucle de eventos asyncio permanece libre para I/O stdio, evitando errores -32602 por corrupción de mensajes.
• Reconexión automática: si la sesión COM queda obsoleta (Access se bloqueó, se cerró manualmente o hay corrupción de COM), el servidor lo detecta mediante una verificación de salud y se reconecta automáticamente en la siguiente llamada de herramienta.
• access_get_code elimina las secciones binarias (PrtMip, PrtDevMode, etc.) de las exportaciones de formularios/informes — access_set_code las restaura automáticamente antes de importar.
• Todos los números de línea de VBE son base 1.

Limitaciones conocidas

• Controles ActiveX (tipo 119 = acCustomControl): access_create_control ahora acepta un parámetro class_name con el ProgID (por ejemplo, Shell.Explorer.2) para inicializar el control OLE. Para WebBrowser específicamente, use el tipo 128 (acWebBrowser) que crea un control nativo sin complejidad OLE. Configurar ctrl.Class desde COM puede no funcionar para todos los controles ActiveX — la inserción manual desde la cinta sigue siendo el método más confiable.
• access_run_vba: Ahora admite procedimientos de módulo de formulario mediante la sintaxis Forms.FormName.Method (acceso COM directo, el formulario debe estar abierto). También admite el parámetro timeout — si se excede, descarta automáticamente los diálogos MsgBox/InputBox. Para una interacción más flexible con formularios, use access_eval_vba.
• Eventos Timer (Form_Timer): Ahora se disparan durante access_screenshot cuando wait_ms > 0 — el bucle de espera bombea mensajes de Windows a través de pythoncom.PumpWaitingMessages(). Otras herramientas aún bloquean el bombeo de mensajes.
• access_vbe_append anteriormente codificaba HTML & como & debido al escape de transporte de MCP. Corregido en v0.7.3 con una decodificación explícita de html.unescape().

Solución de problemas

Errores intermitentes -32602 Invalid request parameters

El SDK de Python de MCP (v1.26.0) tiene un except Exception general en mcp/shared/session.py que se traga los errores reales y devuelve un código genérico -32602 sin detalle. Se aplica un parche local a esta máquina que incluye la excepción real y el traceback en la respuesta de error. Si actualiza el paquete mcp, vuelva a aplicar el parche — consulte CLAUDE.md para obtener detalles.

Historial de cambios

Consulte CHANGELOG.md para ver el historial completo de versiones.