BeyondTrust EPM MCP Server

A Model Context Protocol (MCP) server for managing BeyondTrust Endpoint Privilege Management (EPM) through Claude Desktop and other MCP clients.

Features

• 🔐 Policy Management: Create, read, and manage EPM policies and applications

• 📋 Computer Management: List, authorize, and organize managed endpoints

• 👥 User & Group Management: Manage EPM users, roles, and computer groups

• 🔍 File Inspection: Safely extract file metadata for policy creation (Windows PE files)

• 📊 Audit & Monitoring: Access activity audits, events, and authorization requests

• ✅ Admin Access Requests: Create, approve, and deny admin access requests

Related MCP server: Koppla

🚀 Quick Start

Prerequisites

• Python 3.14 or higher

• uv package manager

• Claude Desktop (or another MCP client)

• BeyondTrust EPM instance with API credentials

Installation

1. Clone the Repository

git clone https://github.com/wesharris222/btepmmcp.git
cd btepmmcp

2. Install Dependencies

uv sync

This installs:

• httpx - HTTP client for EPM API

• mcp - Model Context Protocol SDK

• pefile - PE file parser for file inspection

3. Get Your EPM API Credentials

From your BeyondTrust EPM console:

1. Navigate to Configuration → API Registration

2. Create a new API client

3. Copy the following values:

   • Base URL: https://[your-subdomain]-services.pm.beyondtrustcloud.com

   • Client ID: Your API client ID (GUID)

   • Client Secret: Your API client secret

4. Configure Claude Desktop

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: Edit ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "beyondtrust-epm": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/btepmmcp",
        "run",
        "bt_epm_mcpv1.py"
      ],
      "env": {
        "BT_EPM_BASE_URL": "https://YOUR-SUBDOMAIN-services.pm.beyondtrustcloud.com",
        "BT_EPM_CLIENT_ID": "your-client-id-here",
        "BT_EPM_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Important: Replace the following:

• C:/path/to/btepmmcp → Actual path where you cloned the repo

• YOUR-SUBDOMAIN → Your EPM subdomain

• your-client-id-here → Your API client ID

• your-client-secret-here → Your API client secret

5. Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

6. Verify Installation

In Claude Desktop, try:

List all EPM policies

If configured correctly, Claude will use the MCP server to retrieve your policies!

📖 Usage Examples

Policy Management

List all policies

Show me the details for policy ID 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a

List applications in policy 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a

File Inspection (Safe - No Execution)

Inspect the file at C:\Program Files\7-Zip\7zFM.exe

Returns file properties like:

• File name, size, hashes (SHA256, SHA1)

• Publisher, product name, version

• All metadata without executing the file

Create Policy Application

Create a policy application:
- Policy ID: 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a
- Application Group ID: 5c28a0a9-c133-4f19-9378-0b12f5fe7b77
- Type: exe
- Description: 7-Zip File Manager
- Publisher: Igor Pavlov
- Product Name: 7-Zip

Computer Management

List all computers

Show unauthorized computers

Authorize computer IDs [id1, id2] and assign to group [group-id]

User Management

List all EPM users

Create a user with email john.doe@company.com and role ID [role-id]

Admin Access Requests

Create an admin access request for computer [computer-id]

Approve admin access request [request-id] by user john.doe@company.com

🛠️ Available Tools

The MCP server provides these tools (used automatically by Claude):

Policy Management

• list_policies - List all policies

• get_policy_details - Get detailed policy information

• list_policy_application_groups - List applications in a policy

• create_policy_application - Add applications to policies

File Inspection

• inspect_file_for_policy - Extract file metadata safely

Computer Management

• list_computers - List managed computers

• get_computer_details - Get computer details

• authorize_computers - Authorize computers

• assign_computers_to_group - Assign computers to groups

Group Management

• list_groups - List computer groups

• create_group - Create new groups

User Management

• list_users - List EPM users

• create_user - Create new users

Monitoring & Auditing

• get_activity_audits - Get audit logs

• search_events - Search EPM events

• list_authorization_requests - List authorization requests

• get_authorization_request_details - Get request details

Admin Access Requests

• list_admin_access_requests - List admin access requests

• get_admin_access_request_details - Get request details

• create_admin_access_request - Create new requests

• approve_admin_access_request - Approve requests

• deny_admin_access_request - Deny requests

🔒 Security & Safety

File Inspection Safety

The inspect_file_for_policy tool is 100% safe:

✅ Never executes files - Only reads metadata
✅ Read-only operations - No file modifications
✅ Static analysis only - Parses PE structures without running code
✅ Industry-standard library - Uses trusted pefile library
✅ Cross-platform - Works on Windows, Linux, macOS

See FILE_INSPECTION_README.md for details.

API Security

• Uses OAuth 2.0 client credentials flow

• Credentials stored in Claude Desktop config (local only)

• HTTPS communication with BeyondTrust EPM API

• Token auto-refresh with expiration handling

📁 File Structure

btepmmcp/
├── bt_epm_mcpv1.py              # Main MCP server
├── pyproject.toml               # Python dependencies
├── README.md                    # This file
├── FILE_INSPECTION_README.md    # File inspection guide
├── IMPLEMENTATION_SUMMARY.md    # Technical details
├── QUICK_START.md              # Quick reference
├── test_file_inspection.py     # Safety tests
└── mcp_output/                 # Query results (auto-created)

🧪 Testing

Test File Inspection

uv run python test_file_inspection.py

This verifies:

• Files are not executed

• Metadata is extracted correctly

• Hashes are calculated

• PE parsing works

Manual Testing

# Test file inspection
uv run python -c "from bt_epm_mcpv1 import inspect_file_properties; import json; print(json.dumps(inspect_file_properties('C:\\Windows\\System32\\notepad.exe'), indent=2))"

🌐 Cross-Platform Support

Windows

• Full functionality

• PE file metadata extraction

• Native path support

Linux

• Full API functionality

• Can inspect Windows PE files (.exe, .dll)

• Use Linux paths: /usr/bin/app

macOS

• Full API functionality

• Can inspect Windows PE files

• Use macOS paths: /Applications/App.app/Contents/MacOS/app

📊 Output Files

All query results are saved to mcp_output/:

• latest.json - Last query result (always overwritten)

• <tool>_<timestamp>.json - Archived results for each query

Example:

mcp_output/
├── latest.json
├── list_policies_2025-11-13T10-30-45-123456.json
├── inspect_file_for_policy_2025-11-13T10-35-22-789012.json
└── create_policy_application_2025-11-13T10-40-15-345678.json

⚙️ Configuration Options

Environment Variables

Required (set in Claude Desktop config):

• BT_EPM_BASE_URL - Your EPM instance URL

• BT_EPM_CLIENT_ID - API client ID

• BT_EPM_CLIENT_SECRET - API client secret

Customization

Edit bt_epm_mcpv1.py to customize:

• OUTPUT_DIR (line 17) - Change output directory

• timeout=30.0 (line 146) - Adjust HTTP timeout

• Tool descriptions and parameters

🐛 Troubleshooting

"Missing required environment variables"

Problem: Server can't find API credentials

Solution: Check your claude_desktop_config.json:

1. Verify the path is correct

2. Ensure all three env vars are set

3. No typos in variable names

4. Restart Claude Desktop after changes

"Import pefile could not be resolved"

Problem: Dependencies not installed

Solution:

cd /path/to/btepmmcp
uv sync

"File not found" when inspecting files

Problem: Relative paths or incorrect path format

Solution: Use absolute paths:

• Windows: C:\\Program Files\\App\\app.exe (double backslashes)

• Linux/Mac: /usr/bin/app

"HTTP Error 401 Unauthorized"

Problem: Invalid API credentials

Solution:

1. Verify credentials in EPM console

2. Check Base URL format (must include https://)

3. Ensure client has proper permissions

"HTTP Error 405 Method Not Allowed"

Problem: Incorrect API endpoint (fixed in v1)

Solution: Update to latest version:

git pull origin main

MCP Server Not Loading

Problem: Claude Desktop can't find the server

Solution:

1. Check absolute path in config is correct

2. Verify uv is in your PATH

3. Check Claude Desktop logs:

   • Windows: %APPDATA%\Claude\logs\

   • macOS: ~/Library/Logs/Claude/

   • Linux: ~/.config/Claude/logs/

📚 Additional Resources

• BeyondTrust EPM API Documentation

• Model Context Protocol Specification

• Claude Desktop Documentation

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Test your changes

4. Submit a pull request

📝 License

[Add your license here]

💡 Tips & Best Practices

Policy Creation

1. Inspect files first: Use inspect_file_for_policy to get accurate metadata

2. Use publisher matching: More flexible than hash matching for updates

3. Test with small groups: Verify policies before wide deployment

File Inspection

1. Always use absolute paths: Avoid path resolution issues

2. Review extracted properties: Not all files have all metadata

3. Combine criteria: Use publisher + product name for best results

Security

1. Protect API credentials: Never commit config files with real credentials

2. Use least privilege: Create API clients with minimum required permissions

3. Review audit logs: Monitor MCP server actions in EPM audit logs

🆘 Support

For issues or questions:

1. Check the Troubleshooting section

2. Review the documentation files in this repo

3. Check BeyondTrust EPM API documentation

4. Open an issue on GitHub

✨ What's New

v1.0 (Current)

• ✅ Fixed 405 error in create_policy_application

• ✅ Added cross-platform file inspection

• ✅ PE metadata extraction (publisher, version, hashes)

• ✅ Comprehensive documentation

• ✅ Safety testing suite

🎯 Roadmap

Future enhancements:

• Batch file inspection

• Directory scanning

• Certificate validation

• Policy templates

• Version comparison tools

• Web UI for configuration

Ready to automate your EPM management? Get started now! 🚀