ConnectWise API Gateway MCP Server

This Model Context Protocol (MCP) server provides a comprehensive interface for interacting with the ConnectWise Manage API. It simplifies API discovery, execution, and management for both developers and AI assistants.

Core Capabilities

• API Discovery: Search for and explore ConnectWise API endpoints using keywords or natural language
• Simplified API Execution: Execute API calls with friendly parameter handling and automatic error management
• Fast Memory System: Save and retrieve frequently used API queries for more efficient workflows
• Raw API Access: Send custom API requests with complete control over endpoints, methods, and parameters

Key Features

• Database-Backed API Discovery: Uses a SQLite database built from the ConnectWise API definition JSON for fast, efficient endpoint lookups
• Natural Language Search: Find relevant API endpoints using conversational descriptions of what you need
• Categorized API Navigation: Browse API endpoints organized by functional categories
• Detailed Documentation Access: View comprehensive information about API endpoints including parameters, schemas, and response formats
• Adaptive Learning: The system learns which API calls are most valuable to you through usage tracking

Available Tools

The API Gateway MCP server provides several tools for working with the ConnectWise API:

API Discovery Tools

API Execution Tools

Fast Memory Tools

Understanding Fast Memory

The Fast Memory feature allows you to save and retrieve frequently used API queries, optimizing your workflow in several ways:

Benefits

• Time Savings: Quickly execute complex API calls without remembering exact endpoints or parameters
• Error Reduction: Reuse successful API calls to minimize potential errors
• Adaptive Learning: The system learns which API calls are most valuable to you
• Parameter Persistence: Parameters and request bodies are stored for future use

How It Works

1. Automatic Learning: When you execute a successful API call, you're prompted to save it to Fast Memory
2. Intelligent Retrieval: The next time you use the same API endpoint, the system checks Fast Memory first
3. Parameter Reuse: If you don't provide parameters for a call, the system automatically uses those saved in Fast Memory
4. Usage Tracking: The system tracks how often each query is used and prioritizes frequently used queries

Fast Memory Functionality

• Automatic Parameter Suggestion: The system will suggest parameters from Fast Memory if none are provided
• Usage Counter: Each time a query from Fast Memory is used, its usage count increases
• Search Capability: Search through your saved queries by description or endpoint path
• Prioritization: Queries are displayed in order of usage frequency, with most frequently used queries at the top

Managing Your Fast Memory

• View Saved Queries: list_fast_memory()
• Search Specific Queries: list_fast_memory("search term")
• Delete a Query: delete_from_fast_memory(query_id)
• Clear All Queries: clear_fast_memory()

Fast Memory Technical Details

The Fast Memory system is powered by a SQLite database (fast_memory_api.db) that stores:

• Query paths and methods
• Parameters and request bodies as JSON
• Usage metrics and timestamps
• User-friendly descriptions

The database structure includes:

• id: Unique identifier for each saved query
• description: User-provided description of what the query does
• path: API endpoint path
• method: HTTP method (GET, POST, PUT, etc.)
• params: Query parameters in JSON format
• data: Request body in JSON format
• timestamp: When the query was last used
• usage_count: How many times the query has been used

Installation & Setup

Prerequisites

• Python 3.10 or higher
• Access to ConnectWise Manage API credentials
• ConnectWise API definition file (manage.json) - included in the repository

Installation Steps

Option 1: Using GitHub NPM Package (Recommended)

You can install the package directly from GitHub:

npm install -g jasondsmith72/CWM-API-Gateway-MCP

This method automatically handles all dependencies and provides a simpler configuration for Claude Desktop.

Option 2: Manual Installation

Windows

1. Clone or download the repository:

   Copy

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP

2. Install the package:

   Copy

   pip install -e .

macOS

For the NPM installation method, simply run:

npm install -g jasondsmith72/CWM-API-Gateway-MCP

For manual installation:

1. Install Python 3.10+ if not already installed:

   Copy

   # Using Homebrew
   brew install python@3.10
   
   # Or using pyenv
   brew install pyenv
   pyenv install 3.10.0
   pyenv global 3.10.0

2. Clone the repository:

   Copy

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP

3. Set up a virtual environment (recommended):

   Copy

   python3 -m venv venv
   source venv/bin/activate

4. Install the package:

   Copy

   pip install -e .

Linux (Ubuntu/Debian)

For the NPM installation method, simply run:

sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP

For manual installation:

1. Install Python 3.10+ if not already installed:

   Copy

   # For Ubuntu 22.04+
   sudo apt update
   sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
   
   # For older versions of Ubuntu/Debian
   sudo add-apt-repository ppa:deadsnakes/ppa
   sudo apt update
   sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip

2. Clone the repository:

   Copy

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP

3. Set up a virtual environment (recommended):

   Copy

   python3.10 -m venv venv
   source venv/bin/activate

4. Install the package:

   Copy

   pip install -e .

Post-Installation Steps

After installing on any platform (Windows, macOS, or Linux), complete the following steps:

1. (Optional) Build the API Database

This repository already includes a pre-built database, so this step is optional. Only run this if you need to use a newer ConnectWise API definition file:

# On Windows
python build_database.py path/to/manage.json

# On macOS/Linux
python3 build_database.py path/to/manage.json

This step only needs to be done once, or whenever the ConnectWise API definition changes.

2. Configure API Credentials

Set the following environment variables with your ConnectWise credentials:

CONNECTWISE_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0
CONNECTWISE_COMPANY_ID=your_company_id
CONNECTWISE_PUBLIC_KEY=your_public_key
CONNECTWISE_PRIVATE_KEY=your_private_key
CONNECTWISE_AUTH_PREFIX=yourprefix+  # Prefix required by ConnectWise for API authentication

These credentials are used in the authentication process as follows:

• CONNECTWISE_API_URL: The base URL for all API requests to your ConnectWise instance

  Copy

  url = f"{API_URL}{endpoint}"  # e.g., https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets

• CONNECTWISE_COMPANY_ID: Included in the 'clientId' header of each request to identify your company

  Copy

  headers = {'clientId': COMPANY_ID, ...}

• CONNECTWISE_PUBLIC_KEY and CONNECTWISE_PRIVATE_KEY: Used together with AUTH_PREFIX to create the basic authentication credentials

  Copy

  username = f"{AUTH_PREFIX}{PUBLIC_KEY}"  # e.g., "yourprefix+your_public_key"
  password = PRIVATE_KEY
  credentials = f"{username}:{password}"  # Combined into "yourprefix+your_public_key:your_private_key"

• CONNECTWISE_AUTH_PREFIX: Required prefix added before your public key in the authentication username. ConnectWise API requires this prefix to identify the type of integration (e.g., "api+", "integration+", etc.)

The final HTTP headers sent with every request will look like:

'Authorization': 'Basic [base64 encoded credentials]'
'clientId': 'your_company_id'
'Content-Type': 'application/json'

Configuration for Claude Desktop

There are two methods to integrate with Claude Desktop:

Method 1: Using NPM Package (Recommended)

Install the package using NPM:

npm install -g jasondsmith72/CWM-API-Gateway-MCP

Then configure Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@jasondsmith72/CWM-API-Gateway-MCP"
      ],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

Method 2: Using Node.js Script (Alternate Method)

If you've cloned the repository and installed the dependencies, you can use the included Node.js script:

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "node",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/bin/server.js"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

Method 3: Using Direct Python Script Path

If you prefer to use the Python script directly:

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

For macOS and Linux, use the appropriate path format:

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python3",
      "args": ["/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

The server can be run directly from the command line for testing:

# If installed via NPM
cwm-api-gateway-mcp

# If using the Node.js script (after cloning the repository)
node bin/server.js

# Or using the Python script directly
# On Windows
python api_gateway_server.py

# On macOS/Linux
python3 api_gateway_server.py

Usage Examples

Search for Ticket-Related Endpoints

search_api_endpoints("tickets")

Search Using Natural Language

natural_language_api_search("find all open service tickets that are high priority")

Execute a GET Request

execute_api_call(
    "/service/tickets", 
    "GET", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

Create a New Service Ticket

execute_api_call(
    "/service/tickets", 
    "POST", 
    None,  # No query parameters 
    {
        "summary": "Server is down",
        "board": {"id": 1},
        "company": {"id": 2},
        "status": {"id": 1},
        "priority": {"id": 3}
    }
)

Send a Raw API Request

send_raw_api_request("GET /service/tickets?conditions=status/name='Open'")

View Fast Memory Contents

list_fast_memory()

Save a Useful Query to Fast Memory

save_to_fast_memory(
    "/service/tickets", 
    "GET", 
    "Get all high priority open tickets", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

Advanced Usage

Optimizing API Queries

For better performance with the ConnectWise API:

1. Use Specific Conditions: Narrow your queries with precise conditions

   Copy

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]"
   })

2. Limit Field Selection: Request only the fields you need

   Copy

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "fields": "id,summary,status,priority"
   })

3. Paginate Large Results: Use page and pageSize parameters

   Copy

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "page": 1,
       "pageSize": 50
   })

Troubleshooting

Common Issues

Database Not Found Error

Error: Database file not found at [path]
Please run build_database.py script first to generate the database

Solution: Run the build_database.py script with the path to your ConnectWise API definition file:

python build_database.py path/to/manage.json

API Authentication Issues

HTTP error 401: Unauthorized

Solution: Check your environment variables to ensure all ConnectWise credentials are correct:

• Verify your CONNECTWISE_COMPANY_ID, CONNECTWISE_PUBLIC_KEY, and CONNECTWISE_PRIVATE_KEY
• Ensure the API key has the necessary permissions in ConnectWise
• Check that CONNECTWISE_AUTH_PREFIX is set correctly for your environment

Timeouts on API Calls

Request timed out. ConnectWise API may be slow to respond.

Solution:

• Check your internet connection
• The ConnectWise API may be experiencing high load
• For large data requests, consider adding more specific filters to your query

Logs and Diagnostics

Log Locations

• Main log file: api_gateway/api_gateway.log
• SQLite databases:
  • API Database: api_gateway/connectwise_api.db
  • Fast Memory Database: api_gateway/fast_memory_api.db

Testing the Database

Verify that the database is correctly built and accessible:

python test_database.py

This will display statistics about the database and confirm it can be queried properly.

License

This software is proprietary and confidential. Unauthorized copying, distribution, or use is prohibited.