This repository contains an MCP (Model Context Protocol) server for querying OpenDental documentation using Qdrant vector database.

This tool helps you search through OpenDental documentation using natural language questions. Instead of searching for exact keywords, you can ask questions like "How do I create an appointment?" and get relevant answers from the documentation.

For non-technical users, we've created detailed step-by-step guides:

• Windows Installation and Usage Guide
• macOS Installation and Usage Guide

• Windows, macOS, or Linux
• Node.js 18 or higher (Download here)
• Python 3.6 or higher (Download here)
• Qdrant vector database (automatically runs with Docker or standalone)
• OpenAI API key for generating embeddings (Get one here)

This project requires API keys to function. For security reasons:

• Never commit real API keys to the repository
• Use the provided .env.example files as templates
• Create your own .env files with your actual keys
• The .gitignore file is configured to exclude .env files from Git

If you need to share configuration, always use placeholder values like your_openai_api_key instead of real keys.

git clone https://github.com/yourusername/open-dental-mcp.git
cd open-dental-mcp

git clone https://github.com/yourusername/open-dental-mcp.git
cd open-dental-mcp

You need to have Qdrant running locally. There are several ways to install it:

docker pull qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant

You can download the latest release from Qdrant GitHub releases and run it locally.

You can install Qdrant with Homebrew:

brew install qdrant/qdrant/qdrant
qdrant

You need to set up your environment variables for Qdrant and OpenAI (for embeddings).

1. Create a file named .env in the mcp-openai-filesearch folder based on .env.example
2. Add the following content (replace OpenAI API key with your own):

OPENAI_API_KEY=your_openai_api_key
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=open_dental_docs

1. Create a file named .env in the mcp-openai-filesearch folder based on .env.example
2. Add the following content (replace OpenAI API key with your own):

OPENAI_API_KEY=your_openai_api_key
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=open_dental_docs

From the root directory:

npm run install:deps

Or manually:

cd mcp-openai-filesearch
npm install

cd mcp-openai-filesearch
npm install

From the root directory:

npm run build

Or manually:

cd mcp-openai-filesearch
npm run build

cd mcp-openai-filesearch
npm run build

Before starting the server, you need to set up the Qdrant collection:

cd mcp-openai-filesearch
npm run setup:qdrant

To connect your MCP client (like Cursor) to the OpenDental MCP server, you need to create a configuration file. This tells your client how to launch and communicate with the server.

1. Create a file named mcp.json in the .cursor directory of your project (or where your MCP client looks for configurations)
2. Add the following configuration, adjusting paths to match your local installation:

{
  "mcpServers": {
    "OpenDental-MCP": {
      "command": "node",
      "args": [
        "C:\\path\\to\\open-dental-mcp\\mcp-openai-filesearch\\dist\\server-qdrant.js"
      ],
      "transport": "stdio",
      "description": "Qdrant-based MCP server for OpenDental docs."
    }
  }
}

{
  "mcpServers": {
    "OpenDental-MCP": {
      "command": "/usr/local/bin/node",
      "args": [
        "/path/to/open-dental-mcp/mcp-openai-filesearch/dist/server-qdrant.js"
      ],
      "transport": "stdio",
      "description": "Qdrant-based MCP server for OpenDental docs."
    }
  }
}

1. Command Path:

   • For Windows, you can usually just use "command": "node" if Node.js is in your PATH
   • For macOS/Linux, use the full path to your Node.js binary (find it with which node)

2. Server Path:

   • Make sure to point to server-qdrant.js in the dist directory
   • Use the correct path separator for your OS (\\ for Windows, / for macOS/Linux)
   • Use absolute paths to avoid any confusion

3. Verify Configuration:

   • After creating the mcp.json file, ensure your MCP client can detect and connect to the server
   • If you're using Cursor, go to Settings > MCP and check if "OpenDental-MCP" appears in the list of available servers

From the root directory:

npm run start:qdrant    # Qdrant-based server

Or manually:

cd mcp-openai-filesearch
npm run start:qdrant

cd mcp-openai-filesearch
npm run start:qdrant

The server will start running on http://localhost:3000.

From the root directory:

npm run query:qdrant -- --query "How do I create an appointment in Open Dental?"

Or manually:

cd mcp-openai-filesearch
npm run test:qdrant

cd mcp-openai-filesearch
npm run test:qdrant

If you need to upload your own documentation to the Qdrant vector database:

1. Place your documentation files in a folder
2. Edit the upload script to point to your documentation folder
3. Run the setup script to create embeddings and upload them to Qdrant

1. Path Errors: Make sure to use the correct path format (e.g., C:\path\to\file or C:/path/to/file) in your configuration
2. Permission Denied: Run your command prompt or PowerShell as Administrator if you encounter permission issues
3. NPM Errors: Make sure your Node.js installation is up to date
4. Port Already in Use: If port 3000 or 6333 is already in use, check which process is using it and terminate that process

1. Permission Denied: You may need to use sudo for some commands or fix file permissions with chmod +x filename.py
2. Python Version: Use python3 explicitly rather than python if you have multiple versions installed
3. Port Already in Use: Check if port 3000 is already in use with lsof -i :3000 and kill the process if needed
4. Docker Issues: If using Docker for Qdrant, make sure Docker is running and the Qdrant container is active

• Ensure your OpenAI API key is valid (it's still needed for generating embeddings)
• Make sure there are no extra spaces or characters in the .env file

If you encounter issues not covered here, please:

1. Check the Qdrant documentation
2. Check the OpenAI documentation for embeddings
3. Create an issue in this repository
4. Contact the development team through your organization's support channels

This project is proprietary and confidential.