mcp-msaccess

mcp-access

Dê a qualquer assistente de IA controle total sobre bancos de dados Microsoft Access.

Crie formulários, escreva VBA, projete tabelas, gerencie controles, execute consultas, construa relacionamentos e edite cada canto de um .accdb — tudo por meio de linguagem natural. 69 ferramentas que transformam o Access em algo com o qual você pode conversar.

Nenhuma experiência com Access é necessária. Apenas descreva o que você quer.

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

A IA cuida da automação COM, da visualização de design, dos módulos VBA, das seções binárias, da invalidação de cache e de todas as partes complicadas. Você obtém o resultado.

O que ele pode fazer

• Formulários e Relatórios — criar, clonar, exportar, importar, capturar tela, clicar, digitar. Loop completo de automação de UI
• VBA — ler, escrever, substituir, compilar e executar procedimentos. Edição em nível de linha ou de procedimento completo
• Controles — criar, excluir, modificar, listar, definir ordem de tabulação. Encontra controles aninhados dentro de páginas de TabControl
• Tabelas e SQL — criar via DAO, alterar, consultar, executar em lote, pesquisa de texto completo em todos os campos Texto/Memo. Tabelas vinculadas ODBC suportadas
• Relacionamentos, índices, referências, consultas, macros — CRUD completo. Clone qualquer objeto (formulário / relatório / módulo / classe / consulta / macro) preservando VBA e seções binárias
• Manutenção — compactar e reparar, descompilar bancos de dados inchados, exportar documentos de estrutura. Instalação do Office autodetectada (sem mais caminhos fixos do Office 16)
• Lint de UI — access_lint_form sinaliza layouts objetivamente quebrados (texto branco sobre branco, sobreposições, truncamento, controles fora da tela). Um verificador, não um designer — veja a nota abaixo

Funciona com Claude Code, Cursor, Windsurf, Continue ou qualquer cliente compatível com MCP.

---

Requisitos

• Windows (automação COM é exclusiva para Windows)
• Microsoft Access instalado (qualquer versão que suporte VBE, 2010+)
• Python 3.9+
• "Confiar no acesso ao modelo de objeto do projeto VBA" habilitado na Central de Confiabilidade do Access

Instalação

pip install mcp pywin32

Habilitar acesso ao modelo de objeto VBA

File → Options → Trust Center → Trust Center Settings → Macro Settings → marque Confiar no acesso ao modelo de objeto do projeto VBA

Ou execute o script PowerShell incluído:

.\enable_vba_trust.ps1

Registrar com Claude Code

Global (disponível em todos os projetos):

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

Somente projeto (cria .mcp.json no diretório atual):

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

Registrar com outros clientes MCP

Adicione ao seu arquivo de configuração MCP (.mcp.json, mcp.json ou configurações específicas do cliente):

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

Compatível com qualquer cliente compatível com MCP (Cursor, Windsurf, Continue, etc.).

Ferramentas (69)

Banco de dados

Ferramenta	Descrição
access_create_database	Criar um novo arquivo de banco de dados .accdb vazio
access_close	Fechar a sessão COM e liberar o arquivo .accdb

Objetos do banco de dados

Ferramenta	Descrição
access_list_objects	Listar objetos por tipo (table, module, form, report, query, macro, all). Tabelas do sistema filtradas
access_get_code	Exportar a definição completa de um objeto como texto
access_set_code	Importar texto modificado de volta (cria ou sobrescreve)
access_export_structure	Gerar um índice Markdown de todos os módulos, formulários, relatórios, consultas
access_delete_object	Excluir um módulo, formulário, relatório, consulta ou macro. Requer confirm=true
access_create_form	Criar um novo formulário sem acionar a MsgBox "Salvar como" que bloqueia o COM. has_header opcional para seção de cabeçalho/rodapé, record_source (vincular a tabela/consulta), default_view (0=Único, 1=Contínuo, 2=Folha de dados, ...)

SQL e tabelas

Ferramenta	Descrição
access_execute_sql	Executar SQL via DAO — SELECT retorna linhas como JSON (limit padrão 500). DELETE/DROP/ALTER exigem confirm_destructive=true
access_execute_batch	Executar múltiplas instruções SQL em uma única chamada. Suporta SELECT/INSERT/UPDATE/DELETE mistos com resultados por instrução, stop_on_error e confirm_destructive
access_table_info	Mostrar estrutura da tabela via DAO (campos, tipos, tamanhos, obrigatório, status de vínculo)
access_search_queries	Pesquisar texto no SQL de TODAS as consultas de uma vez (descobrir quais consultas referenciam uma tabela, campo ou palavra-chave)
access_create_table	Criar uma tabela via DAO com suporte completo a tipo, padrão, descrição e chave primária em uma única chamada. Mais robusto que SQL CREATE TABLE
access_alter_table	Modificar estrutura da tabela via DAO: adicionar campo, excluir campo (requer confirm=true), renomear campo

Edição em nível de linha do VBE

Ferramenta	Descrição
access_vbe_get_lines	Ler um intervalo de linhas de um módulo VBA sem exportar o arquivo inteiro
access_vbe_get_proc	Obter o código e a posição de um procedimento pelo nome
access_vbe_module_info	Listar todos os procedimentos com seus números de linha
access_vbe_replace_lines	Substituir/inserir/excluir linhas em um módulo VBA diretamente via VBE
access_vbe_find	Pesquisar texto em UM módulo específico. Uma ocorrência em uma instrução envolvida com _ também retorna a instrução completa unida. Para pesquisar todos os módulos de uma vez, use access_vbe_search_all
access_vbe_search_all	Pesquisar texto em TODOS os módulos/formulários/relatórios do banco de dados de uma vez. Uma ocorrência em uma instrução envolvida com _ também retorna a instrução completa unida. context_lines opcional (0-10) retorna o código ao redor com cada ocorrência
access_vbe_replace_proc	Substituir um procedimento completo pelo nome (calcula automaticamente os limites de linha). Remove linhas Option mal posicionadas, executa verificação estrutural de saúde
access_vbe_patch_proc	Localizar/substituir cirúrgico dentro de um procedimento. Atômico por padrão (um patch com falha não escreve nada), âncoras sem diferenciar maiúsculas/minúsculas, require_unique opcional, correspondência de fallback tolerante a espaços em branco + mensagens de erro contextuais quando patches falham. proc_name='(Declarations)' tem como alvo a seção de declarações
access_vbe_append	Anexar código no final de um módulo. Remove automaticamente Option Explicit/Option Compare para evitar posicionamento incorreto

Controles de formulário e relatório

Ferramenta	Descrição
access_list_controls	Listar todos os controles de um formulário/relatório com propriedades-chave. Valores longos divididos em linhas na exportação são retornados unidos. Controles dentro de Pages/OptionGroups incluem um campo parent. fields opcional mantém apenas as chaves que você solicitar
access_get_control	Obter o bloco de definição completo e sem abreviações de um controle específico — onde ir para uma propriedade que access_list_controls não retorna (encontra controles dentro de Pages/OptionGroups)
access_search_controls	Pesquisar texto ou regex nas propriedades de controle de todos os formulários/relatórios (ControlSource, RowSource, Caption, Tag, Filter… ou properties=["all"]). Valores divididos em linhas de continuação são unidos antes da correspondência
access_create_control	Criar um novo controle via COM na visualização de design. Suporta class_name para inicialização ProgID de ActiveX (tipo 119). Use o tipo 128 (acWebBrowser) para WebBrowser nativo
access_delete_control	Excluir um controle via COM
access_set_control_props	Modificar propriedades de controle via COM na visualização de design
access_set_multiple_controls	Modificar propriedades de múltiplos controles em uma única sessão de visualização de design
access_lint_form	Verificação determinística para layout objetivamente quebrado: contraste (WCAG), sobreposição, fora dos limites, truncamento, inconsistência entre irmãos, tamanho zero/invisível. Retorna verdict PASS/REVIEW/FAIL. Também é executado automaticamente em cada edição de controle

⚠️ Uma nota sobre access_lint_form — gerencie suas expectativas

Isto NÃO é um designer e não há super-design aqui. Não espere que ele faça um formulário parecer bom, sugira uma paleta bonita ou tenha qualquer bom gosto — ele não tem nenhum e nunca terá.

É um verificador burro e determinístico do óbvio e fácil de verificar: o texto tem a mesma cor do fundo? dois controles se sobrepõem fisicamente? uma legenda não cabe na caixa? algo está fora da borda do formulário, ou com zero pixels de altura? Só isso. Matemática simples — proporções de contraste WCAG e interseção de retângulos — com uma pilha de proteções contra falsos positivos para não dar alarme falso.

Pense em cinto de segurança, não estilista: ele não deixa o carro bonito, apenas impede que você envie um formulário com texto branco sobre fundo branco sem perceber. Ele é executado automaticamente em cada edição de controle para que esses erros óbvios apareçam por conta própria. Se você esperava uma IA de design de UI, esta não é (PRs honestos para torná-la mais inteligente são muito bem-vindos 😄).

Exportação/importação de texto

Ferramenta	Descrição
access_export_text	Exportar formulário/relatório/módulo como texto via SaveAsText. NÃO abre a visualização de design. Saída UTF-16 LE
access_import_text	Importar formulário/relatório/módulo de texto via LoadFromText. Substitui se existir. Divide automaticamente VBA CodeBehindForm

Propriedades do banco de dados

Ferramenta	Descrição
access_get_db_property	Ler uma propriedade do banco de dados (CurrentDb.Properties) ou opção do Access (GetOption)
access_set_db_property	Definir uma propriedade do banco de dados ou opção do Access — cria a propriedade se ela não existir
access_get_form_property	Ler propriedades de formulário ou relatório (RecordSource, Caption, DefaultView, etc.). object_type obrigatório (form ou report). Omita property_names para todas
access_set_form_property	Definir propriedades de formulário/relatório (RecordSource, Caption, DefaultView, HasModule, etc.) via COM na visualização de design

Tabelas vinculadas

Ferramenta	Descrição
access_list_linked_tables	Listar tabelas vinculadas com tabela de origem, string de conexão, flag ODBC. name='X' retorna uma tabela; names_only=true é uma listagem leve (sem strings de conexão — use quando centenas de vínculos estouram o resultado); mask_password=true mascara PWD=
access_relink_table	Alterar string de conexão e atualizar vínculo — salva credenciais automaticamente (dbAttachSavePWD) quando UID/PWD são detectados. relink_all=true atualiza todas as tabelas com a mesma conexão original. refresh=true relê o esquema usando a string de conexão da própria tabela (sem new_connect, senha nunca é despejada)

Relacionamentos

Ferramenta	Descrição
access_list_relationships	Listar relacionamentos de tabelas com mapeamentos de campos e flags de cascata
access_create_relationship	Criar um relacionamento entre duas tabelas (suporta atualização/exclusão em cascata)
access_delete_relationship	Excluir um relacionamento pelo nome

Referências VBA

Ferramenta	Descrição
access_list_references	Listar referências do projeto VBA com GUID, caminho, status quebrado/incorporado
access_manage_reference	Adicionar (por GUID ou caminho de arquivo) ou remover uma referência VBA — protege contra remoção de referências incorporadas

Manutenção

Ferramenta	Descrição
access_compact_repair	Compactar e reparar o banco de dados — fecha, compacta para arquivo temporário, troca atomicamente, reabre
access_decompile_compact	Remover p-code VBA órfão via /decompile, recompilar e depois compactar. Redução típica: 60-70% em bancos de dados front-end muito editados. Use quando um .accdb sem dados exceder 30-40 MB

Gerenciamento de consultas

Ferramenta	Descrição
access_manage_query	Criar, modificar, excluir, renomear ou ler SQL de um QueryDef. Excluir requer confirm=true

Índices

Ferramenta	Descrição
access_list_indexes	Listar índices de uma tabela com campos, flags de primário, único, estrangeiro
access_manage_index	Criar ou excluir um índice. Criar requer lista de campos com ordem de classificação opcional

Compilação VBA

Ferramenta	Descrição
access_vbe_check_syntax	Verificação estrutural estática do projeto VBA já aberto — sem descompilação, nada é descartado. A verificação segura pós-edição. Não é um compilador: não resolve identificadores, tipos ou referências
access_compile_vba	Compilar e salvar todos os módulos VBA. timeout opcional para dispensar automaticamente MsgBox de erro. Descompila primeiro e pode descartar VBA não salvo — para uma verificação rápida use access_vbe_check_syntax

Execução de VBA e macros

⚠️ Desativado por padrão (v0.7.51). Estas três ferramentas executam código arbitrário e são controladas pela variável de ambiente MCP_ACCESS_ALLOW_CODE_EXEC. Consulte Segurança para habilitá-las.

Ferramenta	Descrição
access_run_macro	Executa uma macro do Access pelo nome
access_run_vba	Executa uma Sub/Função VBA. Módulos padrão via Application.Run, módulos de formulário via sintaxe Forms.FormName.Method (COM). O parâmetro opcional timeout dispensa automaticamente MsgBox/InputBox
access_eval_vba	Avalia uma expressão VBA via Application.Eval. Funções de domínio, funções internas do VBA, propriedades de formulários abertos, funções de módulos padrão. Fallback automático via módulo temporário para instâncias de classe e outras expressões que o Eval não consegue resolver

Exportar

Ferramenta	Descrição
access_output_report	Exporta um relatório para PDF, XLSX, RTF ou TXT via DoCmd.OutputTo

Transferência de dados

Ferramenta	Descrição
access_transfer_data	Importa/exporta dados entre Access e Excel (.xlsx) ou CSV. Suporta intervalo (Excel) e spec_name (CSV)

Propriedades de campos

Ferramenta	Descrição
access_get_field_properties	Lê todas as propriedades de um campo de tabela (DefaultValue, ValidationRule, Description, Format, etc.)
access_set_field_property	Define uma propriedade de campo — cria a propriedade se ela não existir

Opções de inicialização

Ferramenta	Descrição
access_list_startup_options	Lista 14 opções comuns de inicialização (AppTitle, StartupForm, AllowBypassKey, etc.) com valores atuais

Captura de tela e automação de interface

Ferramenta	Descrição
access_screenshot	Captura a janela do Access como PNG. Opcionalmente abre um formulário/relatório primeiro. Retorna caminho, dimensões (original + imagem) e metadados. max_width configurável (padrão 1920), wait_ms (bombeia mensagens do Windows — eventos de Timer disparam, ActiveX inicializa) e open_timeout_sec (padrão 30 — envia ESC para cancelar se Form_Load travar em uma consulta lenta)
access_ui_click	Clica em coordenadas de imagem na janela do Access. As coordenadas são relativas a uma captura de tela anterior (image_width necessário para dimensionamento). Suporta clique left, double e right
access_ui_type	Digita texto ou envia atalhos de teclado. text para caracteres normais (WM_CHAR), key para teclas especiais (enter, tab, escape, f1-f12, setas, etc.), modifiers para combinações (ctrl, shift, alt)

Referência cruzada

Ferramenta	Descrição
access_find_usages	Pesquisa um nome em código VBA, SQL de consultas e propriedades de controles (ControlSource, RecordSource, RowSource, SourceObject, DefaultValue, ValidationRule, LinkChildFields, LinkMasterFields) em uma única chamada. Cada ocorrência de controle traz o controle proprietário, o valor completo e sua linha

Base de conhecimento

Ferramenta	Descrição
access_tips	Dicas e armadilhas sob demanda. Tópicos: eval, controls, gotchas, sql, vbe, compile, design. Zero tokens até ser chamada

Fluxos de trabalho típicos

Edição VBA direcionada (recomendado)

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

Substituição completa de objetos (formulários, relatórios, módulos)

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

Criando um novo formulário

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 tela e interação com a interface

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

Segurança

Este é um servidor stdio local sem superfície de rede, portanto não há login por design — consulte SECURITY.md para o modelo de ameaça completo. O principal risco é injeção de prompt: um agente enganado (via db_path ou conteúdo que lê do banco de dados) a chamar uma ferramenta de execução de código.

A execução de código está desativada por padrão (v0.7.51). As três ferramentas que executam VBA/Shell arbitrário — access_run_vba, access_eval_vba, access_run_macro — ficam ocultas e são rejeitadas a menos que você opte por ativá-las com uma variável de ambiente. Para reativar, adicione-a ao bloco env deste servidor na configuração do seu cliente MCP e reinicie:

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

Ativar concede execução arbitrária de comandos do sistema operacional; aponte o servidor apenas para bancos de dados confiáveis. Consulte SECURITY.md para detalhes e como relatar problemas.

Variáveis de ambiente

Todas as três são lidas do processo do servidor, portanto vão no bloco env da configuração do seu cliente MCP e entram em vigor na reinicialização.

Variável	Padrão	Efeito
MCP_ACCESS_ALLOW_CODE_EXEC	desligado	Defina como 1/true/yes/on para habilitar access_run_vba, access_eval_vba e access_run_macro. Falha fechada: qualquer outra coisa os mantém desabilitados.
MCP_ACCESS_SHIFT_BYPASS	ligado	Defina como 0/false/no/off para parar de segurar SHIFT durante OpenCurrentDatabase e /decompile. Falha aberta: qualquer outra coisa mantém o bypass.
MCP_ACCESS_EXCLUSIVE	desligado	Defina como 1/true/yes/on para abrir o banco de dados da sessão exclusivamente. Falha fechada: qualquer outra coisa permanece compartilhado.

Sobre o bypass de SHIFT (v0.7.53). Segurar SHIFT é como o servidor pula a macro AutoExec e o formulário de inicialização de um banco de dados, mas o pressionamento de tecla é um global evento do SO — não é limitado ao Access, então qualquer coisa que você digitar em qualquer lugar da máquina enquanto ele estiver pressionado chega capitalizada (~0,3 s em cada troca de banco de dados, ~3 s por descompilação). Desligue se isso incomodar e seus bancos de dados protegerem sua própria inicialização, que é a correção mais limpa e pertence ao banco de dados:

If Not Application.UserControl Then
  Exit Function
End If

Application.UserControl é False quando o Access foi iniciado via COM, então o banco de dados se exclui sob automação e não precisa de bypass algum. Com o bypass desligado, AutomationSecurity e o watchdog de diálogo ainda se aplicam — mas um objeto de macro AutoExec sem proteção será executado.

Sobre aberturas exclusivas (v0.7.55). Aberturas compartilhadas — o padrão, e o que toda versão anterior a esta fazia — não podem obter um bloqueio de design. Anexar Macros de Dados via SaveAsText/LoadFromText, ou qualquer coisa roteada por DoCmd.OpenTable acViewDesign, é recusado para qualquer tabela que outra sessão do Access tenha aberta, uma tabela por vez e sem interromper a execução: ela termina, relata sucesso, e nada mudou. Ative o interruptor e isso se torna uma falha única e visível quando o banco de dados é aberto.

Está desligado por padrão porque é genuinamente exclusivo: a sessão mantém o banco de dados entre chamadas de ferramenta, então enquanto o servidor estiver conectado ninguém mais pode abri-lo. Isso é correto para uma compilação ou uma máquina de desenvolvimento e errado para um front-end compartilhado. access_close libera o banco de dados sem parar o servidor.

O interruptor também verifica o modo em vez de confiar nele. O Access trata Exclusive:=True como uma solicitação: com o arquivo já em uso, ele o abre compartilhado sem dizer nada, e quando outra pessoa o mantém exclusivamente, ele não levanta nada e deixa a sessão sem banco de dados algum. Então o servidor verifica o arquivo de bloqueio antes de abrir (recusando sem tocar na sessão), verifica-o novamente depois (fechando o banco de dados se o Access o rebaixou) e nomeia as sessões que o mantêm no erro. Um arquivo de bloqueio obsoleto deixado por um Access travado não é confundido com um ativo. Com o interruptor ligado, o servidor também para de anexar a uma instância do Access já em execução, que manteria o arquivo compartilhado.

Quando o interruptor está desligado, você ainda é informado (v0.7.56). O padrão permanece compartilhado e nada é recusado, mas se o banco de dados já estiver aberto em outra sessão do Access, o servidor informa isso no resultado da chamada que o abriu, nomeando as sessões que o mantêm. O trabalho de design é o que silenciosamente aterrissa pela metade nesse estado, e a pessoa mais provável de apontar o servidor para um front-end ativo é a menos provável de saber disso. Um banco de dados que outro processo mantém exclusivamente também é relatado como um conflito de bloqueio agora — o Access recusa essa abertura sem um erro e costumava ser diagnosticado como um AutoExec quebrado, o que enviava pessoas à caça através do código de inicialização por um problema de bloqueio.

Notas

• O Access é executado visível (Visible = True) para que o acesso COM do VBE funcione corretamente.
• Uma instância do Access é compartilhada em todas as chamadas de ferramenta (sessão singleton). Abrir um .accdb diferente fecha o anterior.
• Isolamento de thread COM: Todas as chamadas COM são executadas em um executor dedicado de thread única (_com_executor) com CoInitialize(). Isso mantém o COM em uma thread STA enquanto o loop de eventos asyncio permanece livre para E/S stdio, prevenindo erros -32602 de corrupção de mensagens.
• Reconexão automática: se a sessão COM ficar obsoleta (Access travou, fechado manualmente ou corrupção COM), o servidor detecta via uma verificação de saúde e reconecta automaticamente na próxima chamada de ferramenta.
• access_get_code remove seções binárias (PrtMip, PrtDevMode, etc.) de exportações de formulário/relatório — access_set_code as restaura automaticamente antes de importar.
• Todos os números de linha VBE são baseados em 1.

Limitações conhecidas

• Controles ActiveX (tipo 119 = acCustomControl): access_create_control agora aceita um parâmetro class_name com o ProgID (ex.: Shell.Explorer.2) para inicializar o controle OLE. Para WebBrowser especificamente, use o tipo 128 (acWebBrowser) que cria um controle nativo sem complexidade OLE. Definir ctrl.Class via COM pode não funcionar para todos os controles ActiveX — a inserção manual pela faixa de opções continua sendo o método mais confiável.
• access_run_vba: Agora suporta procedimentos de módulo de formulário via sintaxe Forms.FormName.Method (acesso COM direto, o formulário deve estar aberto). Também suporta o parâmetro timeout — se excedido, dispensa automaticamente diálogos MsgBox/InputBox. Para interação mais flexível com formulários, use access_eval_vba.
• Eventos de Timer (Form_Timer): Agora disparam durante access_screenshot quando wait_ms > 0 — o loop de espera bombeia mensagens do Windows via pythoncom.PumpWaitingMessages(). Outras ferramentas ainda bloqueiam o bombeamento de mensagens.
• access_vbe_append anteriormente codificava & em HTML como & devido ao escape do transporte MCP. Corrigido na v0.7.3 com decodificação explícita de html.unescape().

Solução de problemas

Erros intermitentes de -32602 Invalid request parameters

O SDK Python do MCP (v1.26.0) tem um except Exception abrangente em mcp/shared/session.py que engole erros reais e retorna um código -32602 genérico sem detalhes. Um patch local é aplicado nesta máquina que inclui a exceção real e o traceback na resposta de erro. Se você atualizar o pacote mcp, reaplique o patch — consulte CLAUDE.md para detalhes.

Changelog

Consulte CHANGELOG.md para o histórico completo de versões.