MCP Server Overview

The Insites MCP Server connects AI agents to your Insites instance via the Model Context Protocol (MCP). Once configured, you can interact with your contacts, companies, and instance data through natural language commands in Claude Desktop.

What You Can Do

• Contact management - Search, create, and update contacts in your CRM
• Company management - Search, create, and update companies in your CRM
• Instance creation - Create new Insites instances through conversation

For a full list of available tools and their parameters, see the Tools Reference.

Prerequisites

Before starting, make sure you have the following:

• A computer running macOS or Windows
• Python 3.9 or higher - download from python.org
• Git - download from git-scm.com (macOS users can also install via Homebrew: brew install git)
• Claude Desktop - download from claude.ai/download
• An Insites instance with an API key
• Your SERVER_URL - contact Insites support to receive your MCP Server URL

Setup

Step 1: Clone the Repository

Open a terminal and navigate to the directory where you want to install the MCP Server, then clone the repository:

git clone https://github.com/insites-io/module_ai

To update to the latest version later:

cd module_ai
git pull origin master

Step 2: Set Up Python Virtual Environment

Navigate to the module_ai directory, create a virtual environment, and install the required dependencies:

macOS:

cd module_ai
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Windows:

cd module_ai
python -m venv venv
venv/Scripts/activate
pip install --upgrade pip
pip install -r requirements.txt

You can verify the installation was successful by running pip list - you should see packages like fastapi, requests, and PyJWT in the output.

Step 3: Configure Claude Desktop

Open the Claude Desktop configuration file:

• macOS: Click Claude in the menu bar, then Settings, then Developer, then Edit Config
• Windows: Click File, then Settings, then Developer, then Edit Config

If you cannot find it through the menu, open the file manually:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Add an insites-server entry to the mcpServers section with the following configuration:

The following environment variables must be included in the env section:

Make sure all file paths in your configuration are absolute paths (not relative). Save the file when done.

Step 4: Restart Claude Desktop

Your changes take effect only after a full restart. Closing the window is not sufficient - you must fully quit the application.

• macOS: Press Cmd + Q, then reopen Claude Desktop.
• Windows: Click File then Exit, then reopen Claude Desktop.

Verifying the Connection

Once Claude Desktop has restarted:

1. Start a new conversation
2. Look for a hammer icon near the message input area - this indicates MCP tools are active
3. Click the hammer icon to confirm the Insites tools are listed
4. Send a test message: Show me all contacts on my Insites instance

If Claude responds with contact data from your instance, the connection is working correctly.

Updating

To receive the latest updates and bug fixes:

cd module_ai
git pull origin master

Then restart Claude Desktop to apply changes.

Security

• Your API key provides access to your instance data. Keep it secure and never commit it to version control.
• Add your Claude Desktop configuration file to .gitignore if it contains API keys.
• Rotate API keys regularly as a security best practice.

Support

For help with setup, configuration, or troubleshooting, contact Insites support. When reporting an issue, include:

• Your operating system and Python version
• The error message or unexpected behavior
• Whether the issue started after a recent update