fieldcommissioner/Claude-access-mcp

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 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 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 for complete setup and development workflow

📖 Documentation

Start Here

• - Find any documentation quickly
• - Install the .mcpb bundle
• - Complete guide for end users
• - Hands-on 30-minute walkthrough

Reference

• - Complete reference for all 52 tools
• - Developer API documentation
• - Frequently asked questions

For Developers

• - How to contribute
• - Production deployment
• - ADRs documenting key decisions
• - Technical architecture (LAW)

Project Status

• - Project status and technical debt
• - Version history
• - 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 .

🧪 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:

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:

1. Download ACE from Microsoft: https://www.microsoft.com/download/details.aspx?id=54920
2. Install the 64-bit version (matches server architecture)
3. Restart the MCP server
4. 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

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

Commit Message Format

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

<body>

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

📊 Project Status

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

See for detailed progress tracking.

📝 License

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

Third-Party Licenses

This project uses several open-source libraries and components. See the 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:
• Specification:
• Model Context Protocol: https://modelcontextprotocol.io
• Claude Desktop: https://claude.ai/download

📚 Additional Resources

• Complete Tool Reference: See for detailed tool catalog
• Phase-by-Phase Implementation: See for implementation timeline
• Code Quality Reports: See phase-specific code reviews in

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