Access MCP Server

Model Context Protocol server for Microsoft Access database automation

Latest Release v1.0.5 (Oct 10, 2025): Sprint 2 complete - 100% test pass rate achieved (492/492 active tests). Fixed critical MSACCESS.EXE file lock issue (BUG-010) that was blocking git operations. All database file locks now properly released on disconnect. See CHANGELOG.md for complete details.

📋 Overview

Access MCP Server enables AI assistants (like Claude) to directly interact with Microsoft Access databases through the Model Context Protocol. It provides 52 tools across 5 phases plus diagnostic tools for complete database automation.

Features

✅ Phase 1 Complete: 15 core data operation tools (connect, query, schema discovery)
✅ Phase 2 Complete: 10 DDL tools (create/alter/drop tables, relationships, indexes)
✅ Phase 3 Complete: 10 VBA code manipulation tools (read, write, export, import, compile)
✅ Phase 4 Complete: 8 forms and reports automation tools (list, inspect, export, import)
✅ Phase 5 Complete: 7 advanced database administration tools (compact, analyze, backup, split, dependencies)

Quick Stats

Tools Implemented: 52/52 (100%)
Version: 1.1.0 (Production Ready)
Build Status: ✅ Passing (0 errors, 1 warning)
Test Coverage: 100% (492/492 active tests passing, 9 skipped)
Current Phase: ✅ All 5 Phases Complete + Sprints 1 & 2!

🚀 Quick Start

Prerequisites

Required:

Windows 10/11 (64-bit) or Windows Server 2016+
.NET 8.0 Runtime
Access Database Engine (ACE) 2016 or later (64-bit) ⚠️ REQUIRED

Optional:

Claude Desktop (for MCP integration)
Microsoft Access 2016+ (for VBA and Forms/Reports tools)

⚠️ Important: Access Database Engine Requirements

The Access Database Engine (ACE) is required for this server to function. Without it, all database operations will fail.

Minimum Version: ACE 2016 (recommended for best compatibility)
Architecture: Must be 64-bit to match the server
Download: Microsoft Access Database Engine 2016 Redistributable

Version Compatibility:

✅ ACE 2016/2019/365: Full compatibility with all database formats
⚠️ ACE 2010-2013: Limited compatibility (some Access 2016+ databases may fail)
❌ ACE 2007 or earlier: Not recommended (significant compatibility issues)

Troubleshooting:

The server performs automatic ACE version detection on startup
If ACE is missing or outdated, clear error messages will guide you
Check server logs for ACE version and compatibility warnings
See System Requirements section below for detailed requirements

Installation

For End Users:

See Installation Guide for .mcpb bundle installation in Claude Desktop

For Developers:

# Clone repository
git clone https://github.com/fieldcommissioner/Claude-access-mcp.git
cd Claude-Access-MCP

# Build project
dotnet build

# Run tests
dotnet test

# Note: 9 Phase 3 (VBA) tests will skip unless VBA access is enabled
# See docs/QUICK_START_VBA_TESTS.md for instructions

For Contributors:

See CONTRIBUTING.md for complete setup and development workflow

📖 Documentation

Start Here

Documentation Navigation - Find any documentation quickly
Installation Guide - Install the .mcpb bundle
User Guide - Complete guide for end users
Tutorial - Hands-on 30-minute walkthrough

Reference

Tools Reference - Complete reference for all 52 tools
API Reference - Developer API documentation
FAQ - Frequently asked questions

For Developers

Contributing Guide - How to contribute
Deployment Guide - Production deployment
Architecture Decisions - ADRs documenting key decisions
Project Specification - Technical architecture (LAW)

Project Status

ROADMAP - Project status and technical debt
CHANGELOG - Version history
Project Complete - Completion summary

🛠️ Available Tools

Phase 1: Core Data Operations (15 tools) ✅

Connection Management (4 tools)

connect_database - Connect to Access database
disconnect_database - Close connection
list_connections - List active connections
is_connected - Check connection status

Schema Discovery (6 tools)

get_tables - List all tables
get_table_schema - Get column definitions
get_indexes - List table indexes
get_relationships - Get foreign key relationships
get_queries - List saved queries
get_query_definition - Get query SQL

Data Operations (5 tools)

query_data - Execute SELECT queries
execute_update - Execute INSERT/UPDATE/DELETE
execute_transaction - Multi-statement ACID transactions
get_record_count - Count records in table
table_exists - Check if table exists

Phase 2: Schema Management (10 tools) ✅

Table Operations (4 tools)

create_table - Create new table with columns ✅ ADOX
alter_table - Modify table structure ✅ ADOX
drop_table - Delete table ✅ SQL
rename_table - Rename table ✅ ADOX

Relationship Management (3 tools)

create_relationship - Add foreign key ✅ ADOX
drop_relationship - Remove foreign key ✅ ADOX
get_relationship_details - Get FK details ✅ ADOX

Index Management (3 tools)

create_index - Create index ✅ ADOX
drop_index - Remove index ✅ ADOX
analyze_index_usage - Index performance analysis ✅ ADOX

Phase 3: VBA Code Manipulation (10 tools) ✅

Module Operations (4 tools)

list_vba_modules - List all VBA modules with metadata ✅
get_vba_code - Retrieve VBA source code ✅
set_vba_code - Set/replace VBA code ✅
add_vba_procedure - Add Sub/Function/Property ✅

Import/Export (2 tools)

export_vba_to_files - Export to .bas/.cls/.frm files ✅
import_vba_from_files - Import from text files ✅

Reference & Compilation (4 tools)

get_vba_references - List VBA references ✅
check_broken_references - Find broken references ✅
compile_vba - Compile VBA project ✅
get_vba_project_properties - Get project metadata ✅

Phase 4: Forms and Reports (8 tools) ✅

Form/Report Management (8 tools)

list_forms - List all forms with metadata ✅
list_reports - List all reports with metadata ✅
get_form_controls - Get control hierarchy for a form ✅
get_control_properties - Read all properties of a control ✅
export_form_to_text - Export form to text file (version control) ✅
import_form_from_text - Import form from text file ✅
export_report_to_text - Export report to text file (version control) ✅
import_report_from_text - Import report from text file ✅

Phase 5: Advanced Database Administration (7 tools) ✅

Database Maintenance (3 tools)

backup_database - Create verified backup copy ✅
compact_database - Compact & repair to reclaim space ✅
get_database_properties - Get comprehensive metadata ✅

Database Management (4 tools)

analyze_database - Health analysis with recommendations ✅
split_database - Split into frontend/backend ✅
query_system_tables - Query MSys* tables for low-level metadata ✅
get_object_dependencies - Analyze object dependencies ✅

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│          MCP Protocol (JSON-RPC over stdio)         │
└─────────────────────────────────────────────────────┘
                         ↕
┌─────────────────────────────────────────────────────┐
│              MCP Tools (52 total)                   │
│  Connection(4) | Schema(6) | Data(5) | DDL(10)     │
│  VBA(10) | Forms(8) | Admin(7) | Diagnostic(2)     │
└─────────────────────────────────────────────────────┘
                         ↕
┌─────────────────────────────────────────────────────┐
│              Service Layer                           │
│  IOleDbService | IComInteropService (future)        │
│  IConnectionRegistry | CallToolResultFactory        │
└─────────────────────────────────────────────────────┘
                         ↕
┌─────────────────────────────────────────────────────┐
│         Data Access Layer                            │
│  System.Data.OleDb | ADOX (COM) | Access Interop    │
└─────────────────────────────────────────────────────┘

💡 Usage Examples

Phase 5: Database Administration

// Analyze database health
const analysis = await claude.useTool("analyze_database", {
  databasePath: "C:\\Projects\\myapp.accdb"
});
// Returns: file size, object counts, recommendations, warnings

// Compact database to reclaim space
const compact = await claude.useTool("compact_database", {
  databasePath: "C:\\Projects\\myapp.accdb",
  backupPath: "C:\\Backups\\myapp_backup.accdb"  // optional
});
// Returns: space reclaimed, before/after sizes

// Split database for multi-user deployment
const split = await claude.useTool("split_database", {
  databasePath: "C:\\Projects\\myapp.accdb",
  backendPath: "C:\\Server\\myapp_be.accdb"
});
// Creates: frontend (UI) + backend (data), links tables

// Analyze object dependencies
const deps = await claude.useTool("get_object_dependencies", {
  databasePath: "C:\\Projects\\myapp.accdb",
  objectName: "Customers"
});
// Returns: what uses this object, what it uses

// Query system tables for metadata
const sysTables = await claude.useTool("query_system_tables", {
  databasePath: "C:\\Projects\\myapp.accdb",
  tableName: "MSysObjects"
});
// Returns: low-level Access metadata

For complete examples of all 52 tools, see ROADMAP.md.

🧪 Testing

# Run all unit tests
dotnet test --filter "FullyQualifiedName!~Integration"

# Run with coverage
dotnet test --collect:"XPlat Code Coverage" --filter "FullyQualifiedName!~Integration"

# Run specific test project
dotnet test tests/MS.Access.MCP.Server.Tests/

# Run integration tests (requires Access Database Engine)
dotnet test --filter "FullyQualifiedName~Integration"

Current Status:

✅ 349 unit tests passing (Phases 1-5 complete)
✅ Integration tests implemented (Phases 1 & 2)
✅ Test coverage >80% across all phases

💻 System Requirements

Minimum Requirements

Operating System:

Windows 10 (64-bit) version 1809 or later
Windows 11 (64-bit)
Windows Server 2016 or later

Runtime:

.NET 8.0 Runtime (x64)
Download: https://dotnet.microsoft.com/download/dotnet/8.0

Database Engine:

Access Database Engine (ACE) 2010 or later (64-bit)
Minimum: ACE 2010 (limited compatibility)
Recommended: ACE 2016 or later (full compatibility)
Download: https://www.microsoft.com/download/details.aspx?id=54920

Recommended Requirements

For Best Experience:

ACE 2016/2019/365 (latest version)
Microsoft Access 2016+ (for VBA and Forms/Reports features)
4GB RAM minimum (8GB recommended for large databases)
SSD storage for optimal database performance

Optional Components

For Advanced Features:

Microsoft Access 2016+ - Required for:
- VBA code manipulation (Phase 3 tools)
- Forms and reports automation (Phase 4 tools)
- Advanced COM automation features
Visual Basic for Applications (VBA) - Included with Access

Database Format Compatibility

The server automatically detects and validates database compatibility:

Database Format	ACE 2010	ACE 2013	ACE 2016+	Status
Access 97-2003 (.mdb)	✅	✅	✅	Full support
Access 2007-2013 (.accdb)	✅	✅	✅	Full support
Access 2016 (.accdb)	⚠️	⚠️	✅	Requires ACE 2016+
Access 2019/365 (.accdb)	❌	❌	✅	Requires ACE 2016+

Note: The server performs automatic compatibility validation on database connection and provides clear error messages if the database format is incompatible with your installed ACE version.

Compatibility Validation

The server includes built-in diagnostics:

Startup Check: Detects ACE version on server start
Connection Check: Validates database compatibility before connecting
Clear Errors: Provides remediation steps if compatibility issues found
Logging: Records ACE version and compatibility warnings in logs

Installation Verification

After installing prerequisites, verify your setup:

# Check .NET version
dotnet --version

# Check ACE installation (via registry)
# The server will automatically detect and report ACE version on startup

# Build and run server
dotnet build
dotnet run --project src/MS.Access.MCP.Server

The server will log ACE version detection results:

[INFO] Access Database Engine detected: ACE 2016/2019/365
[INFO] ACE version is up to date and fully compatible

Troubleshooting

ACE Not Detected:

Download ACE from Microsoft: https://www.microsoft.com/download/details.aspx?id=54920
Install the 64-bit version (matches server architecture)
Restart the MCP server
Check logs for ACE detection confirmation

Database Compatibility Issues:

Error: "The database you are trying to open requires a newer version of Microsoft Access"
Solution: Upgrade to ACE 2016 or later, or downgrade database format in Access

Architecture Mismatch:

Ensure you install 64-bit ACE (not 32-bit)
The server is compiled for x64 and requires matching ACE version

🤝 Contributing

This is a work-in-progress project. Contributions welcome!

Development Workflow

Read ROADMAP.md for current status
Follow specifications in .claude/ directory (LAW)
Create feature branch from master
Implement with tests
Ensure dotnet build passes (0 errors, 0 warnings)
Submit pull request

Commit Message Format

<type>(<scope>): <subject>

<body>

Types: feat, fix, docs, refactor, test, chore

📊 Project Status

Phase	Status	Tools	Progress
Phase 1: Core Data	✅ Complete	15/15	100%
Phase 2: DDL	✅ Complete	10/10	100%
Phase 3: VBA	✅ Complete	10/10	100%
Phase 4: Forms	✅ Complete	8/8	100%
Phase 5: Admin	✅ Complete	7/7	100%
Diagnostic	✅ Complete	2/2	100%
TOTAL	✅ 100%	52/52	100%

🎉 All 5 phases complete + diagnostic tools! Full-featured Microsoft Access automation via MCP.

See ROADMAP.md for detailed progress tracking.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Licenses

This project uses several open-source libraries and components. See the NOTICE file for complete attribution and license information for all dependencies.

Key Components:

ModelContextProtocol SDK - MIT License
System.Data.OleDb - MIT License
xUnit, Moq, Coverlet - MIT/Apache/BSD Licenses
ADOX (COM Interop) - Requires Microsoft Access Database Engine (Proprietary)

🔗 Links

Documentation: ROADMAP.md
Specification: .claude/project specification.md
Model Context Protocol: https://modelcontextprotocol.io
Claude Desktop: https://claude.ai/download

📚 Additional Resources

Complete Tool Reference: See PROJECT_COMPLETE.md for detailed tool catalog
Phase-by-Phase Implementation: See ROADMAP.md for implementation timeline
Code Quality Reports: See phase-specific code reviews in docs/

Last Updated: 2025-10-10 Version: 1.1.0 (Production Ready) Status: ✅ All Critical Bugs Fixed - 100% Test Pass Rate Next: Phase 6.2 - LLM Context Document

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
dist		dist
docs		docs
packaging		packaging
scripts		scripts
src/MS.Access.MCP.Server		src/MS.Access.MCP.Server
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MS.Access.MCP.Server.sln		MS.Access.MCP.Server.sln
NOTICE		NOTICE
PHASE_6.3_PROGRESS_SUMMARY.md		PHASE_6.3_PROGRESS_SUMMARY.md
README.md		README.md
ROADMAP.md		ROADMAP.md

Latest commit

History

Folders and files

Repository files navigation