itarundaniel-ad-mcp-server 0.1.0
Active Directory MCP Server - Query AD data from JSON exports using Claude AI
License: MIT
Requires Python: >=3.10

# Active Directory MCP Server

A Model Context Protocol (MCP) server that allows Claude Desktop to query your Active Directory data from the `ad.json` file.

## Features

The server provides these tools to Claude:

1. **search_ad** - Search for users, groups, computers by name, email, or username
2. **get_user_details** - Get detailed information about a specific user (group memberships, last logon, etc.)
3. **get_group_members** - List all members of a specific AD group
4. **list_groups** - List all groups, optionally filtered by name
5. **get_ad_statistics** - Get overview statistics about your AD environment

## Setup Instructions

### Step 1: Create Virtual Environment

Open Command Prompt or PowerShell in this directory and run:

```bash
# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows Command Prompt:
venv\Scripts\activate
# On Windows PowerShell:
venv\Scripts\Activate.ps1
```

### Step 2: Install Python Dependencies

With the virtual environment activated, install the dependencies:

```bash
pip install -r requirements.txt
```

### Step 3: Test the Server (Optional)

You can test if the server loads correctly by running:

```bash
python ad_mcp_server.py
```

If it loads successfully, you'll see:
```
Loading AD data from ad.json...
Loaded 10068 objects from hoan.com domain
```

Then press `Ctrl+C` to stop it. Don't worry if nothing else happens - the server is waiting for MCP protocol messages.

### Step 4: Configure Claude Desktop

1. **Locate your Claude Desktop config file:**
   - On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Full path is usually: `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`

2. **Edit the config file** and add the MCP server configuration:

```json
{
  "mcpServers": {
    "active-directory": {
      "command": "C:\\Users\\arudani\\cstuff\\addsjson\\mcp\\venv\\Scripts\\python.exe",
      "args": [
        "ad_mcp_server.py"
      ],
      "cwd": "C:\\Users\\arudani\\cstuff\\addsjson\\mcp"
    }
  }
}
```

**Important Notes:**
- Use the **full path to the Python executable in your virtual environment**
- Use double backslashes (`\\`) in Windows paths
- The `args` now just contains the script name (not full path)
- The `cwd` sets the working directory where the script and ad.json are located
- If you have other MCP servers configured, add this as another entry in the `mcpServers` object

3. **Restart Claude Desktop** completely (quit and relaunch)

### Step 5: Verify Connection

1. Open Claude Desktop
2. Look for a hammer icon or tools indicator in the interface
3. You should see 5 tools available from the "active-directory" server

## Usage Examples

Once configured, you can ask Claude questions like:

- "Search for users named John"
- "Who is in the Domain Admins group?"
- "Get details for user jsmith"
- "List all groups containing 'AWS' in the name"
- "Show me statistics about the Active Directory"
- "Find all users in the IT department"
- "What groups is gentran@hoan.com a member of?"

Claude will automatically use the appropriate MCP tools to query your AD data.

## Troubleshooting

### Server doesn't appear in Claude Desktop

1. Check that the config file path is correct
2. Make sure you used double backslashes in Windows paths
3. Verify the Python path is correct (try `where python` in Command Prompt)
4. Check Claude Desktop logs at: `%APPDATA%\Claude\logs\`
5. Restart Claude Desktop completely

### "AD data not loaded" errors

- Make sure `ad.json` is in the same directory as `ad_mcp_server.py`
- Check that the JSON file is valid and not corrupted

### Python not found

- Make sure Python is installed and in your PATH
- You may need to use `python3` instead of `python` in the config
- Or use the full path to Python: `C:\\Python311\\python.exe`

## File Structure

```
mcp/
├── venv/                  # Virtual environment (created during setup)
├── ad_mcp_server.py      # The MCP server code
├── requirements.txt       # Python dependencies
├── ad.json               # Your Active Directory data
└── README.md             # This file
```

## Sharing with Your Team

To share this with colleagues:

1. Share these files: `ad_mcp_server.py`, `requirements.txt`, and `ad.json`
2. Each person needs to:
   - Create their own virtual environment (`python -m venv venv`)
   - Activate the virtual environment
   - Install the dependencies (`pip install -r requirements.txt`)
   - Have a copy of `ad.json` in the same folder
   - Configure their Claude Desktop config file with the correct paths (pointing to their venv Python)
   - Restart Claude Desktop

**Note:** Do NOT share the `venv` folder - each person should create their own virtual environment.

## Security Note

The `ad.json` file contains your organization's Active Directory data. Keep it secure and only share with authorized personnel.