Content
# 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
## 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:
```bash
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:**
```bash
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
cd CWM-API-Gateway-MCP
```
2. **Install the package:**
```bash
pip install -e .
```
#### macOS
For the NPM installation method, simply run:
```bash
npm install -g jasondsmith72/CWM-API-Gateway-MCP
```
For manual installation:
1. **Install Python 3.10+ if not already installed:**
```bash
# 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:**
```bash
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
cd CWM-API-Gateway-MCP
```
3. **Set up a virtual environment (recommended):**
```bash
python3 -m venv venv
source venv/bin/activate
```
4. **Install the package:**
```bash
pip install -e .
```
#### Linux (Ubuntu/Debian)
For the NPM installation method, simply run:
```bash
sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP
```
For manual installation:
1. **Install Python 3.10+ if not already installed:**
```bash
# 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:**
```bash
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
cd CWM-API-Gateway-MCP
```
3. **Set up a virtual environment (recommended):**
```bash
python3.10 -m venv venv
source venv/bin/activate
```
4. **Install the package:**
```bash
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:
```bash
# 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
```
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
```
headers = {'clientId': COMPANY_ID, ...}
```
- **CONNECTWISE_PUBLIC_KEY** and **CONNECTWISE_PRIVATE_KEY**: Used together with AUTH_PREFIX to create the basic authentication credentials
```
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:
```bash
npm install -g jasondsmith72/CWM-API-Gateway-MCP
```
Then configure Claude Desktop (`claude_desktop_config.json`):
```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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```bash
# 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
```
## Available Tools
The API Gateway MCP server provides several tools for working with the ConnectWise API:
### API Discovery Tools
| Tool | Description |
|------|-------------|
| `search_api_endpoints` | Search for API endpoints by query string |
| `natural_language_api_search` | Find endpoints using natural language descriptions |
| `list_api_categories` | List all available API categories |
| `get_category_endpoints` | List all endpoints in a specific category |
| `get_api_endpoint_details` | Get detailed information about a specific endpoint |
### API Execution Tools
| Tool | Description |
|------|-------------|
| `execute_api_call` | Execute an API call with path, method, parameters, and data |
| `send_raw_api_request` | Send a raw API request in the format "METHOD /path [JSON body]" |
### Fast Memory Tools
| Tool | Description |
|------|-------------|
| `save_to_fast_memory` | Manually save an API query to Fast Memory |
| `list_fast_memory` | List all queries saved in Fast Memory |
| `delete_from_fast_memory` | Delete a specific query from Fast Memory |
| `clear_fast_memory` | Clear all queries from Fast Memory |
## Usage Examples
### Search for Ticket-Related Endpoints
```python
search_api_endpoints("tickets")
```
### Search Using Natural Language
```python
natural_language_api_search("find all open service tickets that are high priority")
```
### Execute a GET Request
```python
execute_api_call(
"/service/tickets",
"GET",
{"conditions": "status/name='Open' and priority/name='High'"}
)
```
### Create a New Service Ticket
```python
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
```python
send_raw_api_request("GET /service/tickets?conditions=status/name='Open'")
```
### View Fast Memory Contents
```python
list_fast_memory()
```
### Save a Useful Query to Fast Memory
```python
save_to_fast_memory(
"/service/tickets",
"GET",
"Get all high priority open tickets",
{"conditions": "status/name='Open' and priority/name='High'"}
)
```
## 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
## 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:
```bash
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:
```bash
python test_database.py
```
This will display statistics about the database and confirm it can be queried properly.
## Advanced Usage
### Optimizing API Queries
For better performance with the ConnectWise API:
1. **Use Specific Conditions:** Narrow your queries with precise conditions
```python
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
```python
execute_api_call("/service/tickets", "GET", {
"conditions": "status/name='Open'",
"fields": "id,summary,status,priority"
})
```
3. **Paginate Large Results:** Use page and pageSize parameters
```python
execute_api_call("/service/tickets", "GET", {
"conditions": "status/name='Open'",
"page": 1,
"pageSize": 50
})
```
## License
This software is proprietary and confidential. Unauthorized copying, distribution, or use is prohibited.
## Acknowledgments
- Built using the Model Context Protocol (MCP) framework
- Powered by ConnectWise Manage API
