dolibarr-mcp/MCP_FIX_GUIDE.md

MCP Server Installation Fix Guide

Quick Fix (Recommended)

If you're experiencing the "ModuleNotFoundError: No module named 'dolibarr_mcp'" error, follow these steps:

Step 1: Run Diagnostic Tool

python diagnose_and_fix.py

This will automatically identify and fix most issues.

Step 2: Run Installation Fix

fix_installation.bat

This ensures the package is properly installed.

Step 3: Test the Server

python mcp_server_launcher.py

Manual Fix Steps

If the automatic fixes don't work:

1. Ensure You're in the Right Directory

cd C:\Users\[YOUR_USERNAME]\GitHub\dolibarr-mcp

2. Create/Activate Virtual Environment

python -m venv venv_dolibarr
venv_dolibarr\Scripts\activate

3. Install Package in Development Mode

pip install -e .

4. Install Required Dependencies

pip install requests python-dotenv mcp

5. Configure Environment

Create a .env file with your Dolibarr credentials:

DOLIBARR_URL=https://your-dolibarr.com/api/index.php
DOLIBARR_API_KEY=your-api-key-here

6. Update Claude Desktop Configuration

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "dolibarr-python": {
      "command": "C:\\Users\\[YOUR_USERNAME]\\GitHub\\dolibarr-mcp\\venv_dolibarr\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\[YOUR_USERNAME]\\GitHub\\dolibarr-mcp\\mcp_server_launcher.py"
      ]
    }
  }
}

Common Issues and Solutions

Issue: ModuleNotFoundError

Solution: The package isn't installed. Run:

pip install -e .

Issue: ImportError for dependencies

Solution: Install missing dependencies:

pip install requests python-dotenv mcp aiohttp pydantic

Issue: Server starts but immediately stops

Solution: Check your .env file has valid credentials

Issue: "No module named 'src'"

Solution: You're running from wrong directory. Navigate to project root:

cd C:\Users\[YOUR_USERNAME]\GitHub\dolibarr-mcp

Testing the Installation

Test 1: Check Module Import

python -c "from src.dolibarr_mcp import __version__; print(f'Version: {__version__}')"

Test 2: Run Server Directly

python src/dolibarr_mcp/dolibarr_mcp_server.py

Test 3: Check MCP Connection

python test_connection.py

File Structure Verification

Ensure these files exist:

dolibarr-mcp/
├── src/
│   └── dolibarr_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── dolibarr_mcp_server.py
│       ├── dolibarr_client.py
│       └── config.py
├── .env (with your credentials)
├── setup.py
├── pyproject.toml
├── mcp_server_launcher.py
├── diagnose_and_fix.py
└── fix_installation.bat

Support

If you continue to experience issues:

1. Run diagnose_and_fix.py and share the output
2. Check the GitHub Issues
3. Ensure you have Python 3.8+ installed
4. Try the alternative ultra-simple server: python src/dolibarr_mcp/ultra_simple_server.py

Alternative: Docker Installation

If local installation continues to fail, use Docker:

docker-compose up

This will run the server in an isolated container with all dependencies pre-configured.