MCP PGVector Server

A Model Context Protocol (MCP) server that provides powerful semantic search and data retrieval capabilities for PostgreSQL databases enhanced with the pgvector extension.

This server acts as a bridge between a large language model (like Anthropic's Claude) and your database, allowing the model to query your data using natural language. It supports multiple embedding providers (OpenAI, Azure, Hugging Face) to turn text into vectors for semantic search.

Features

• Semantic Vector Search: Find database records based on meaning, not just keywords.
• Metadata Filtering: Combine semantic search with precise, attribute-based filtering.
• Dynamic Schema Discovery: Automatically discovers tables and vector columns.
• Automatic Embedding: Automatically converts document content into vector embeddings upon insertion.
• Multi-Provider Support: Use embeddings from OpenAI, Azure OpenAI, or Hugging Face.
• Standardized Protocol: Implements the Model Context Protocol (MCP) for easy integration with any MCP-compatible client.

🚀 Quick Start

The easiest way to run the server is with npx, which will download and run the package without a manual installation.

Prerequisites:

• Node.js v18 or higher
• A PostgreSQL database with the pgvector extension enabled (CREATE EXTENSION IF NOT EXISTS vector;).

Run Command: Set the required environment variables and run the server.

# Example using OpenAI embeddings
export DATABASE_URL="postgresql://user:pass@host:port/db"
export OPENAI_API_KEY="sk-your-key-here"

npx rbm-rag-mcp-server

The server will start and listen for requests on standard I/O, as expected by an MCP client.

⚙️ Configuration

Configuration is managed via environment variables.

| Variable | Required | Description | Default | |---|---|---|---| | DATABASE_URL | Yes | Full connection string for your PostgreSQL database. | | | DB_SCHEMA | No | The database schema to operate in. | vecs | | DB_DEFAULT_TABLE | No | The default table to use for queries if not specified. | document_embeddings | | EMBEDDING_PROVIDER| No | Force a specific embedding provider. | auto | | OPENAI_API_KEY | No* | Your OpenAI API key. | | | AZURE_OPENAI_API_KEY| No* | Your Azure OpenAI API key. | | | AZURE_OPENAI_ENDPOINT| No* | Your Azure OpenAI resource endpoint. | | | HUGGINGFACE_API_KEY| No* | Your Hugging Face API key. | |

*At least one embedding provider key is required for vector search and document insertion features.

🤖 Claude Integration

This server is designed to be used as a tool by an AI model like Anthropic's Claude. By exposing the server's capabilities as tools, you can empower Claude to query your database to answer questions or find information.

Here’s a conceptual guide to integrating this server with Claude:

1. Expose the Server's Tools to Claude

First, you need to present the available functions to Claude in the tools parameter of your API call. You can get the exact tool definitions by running the server and sending a tools/list request, but here is a summary:

• vector_search(query, table, limit, similarity_threshold): Performs semantic search.
• metadata_search(filters, table, limit): Filters documents based on metadata.
• insert_document(content, metadata, table): Adds a new document.
• get_database_stats(): Retrieves statistics about the database.
• get_table_schemas(): Gets the schema for all tables in the configured schema.

2. Handle Claude's Tool Use Request

When Claude decides to use one of your tools, your application will receive a tool_use block in the API response. Your code needs to: a. Parse the tool_name and input from Claude's request. b. Construct a corresponding JSON-RPC request to this MCP server. c. Send the request to the server and await the response. d. Pass the server's response back to Claude in a subsequent API call.

Conceptual Example (Python Pseudocode):

import anthropic
import json
import subprocess

# Assume you have the server's tool definitions
from my_app import mcp_tools_definition 

client = anthropic.Anthropic()

# Start the MCP server as a subprocess
mcp_server_process = subprocess.Popen(
    "npx rbm-rag-mcp-server",
    shell=True,
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
    env={"DATABASE_URL": "...", "OPENAI_API_KEY": "..."}
)

def call_mcp_tool(tool_name, tool_input):
    """Calls the MCP server and gets a response."""
    # 1. Format the request in JSON-RPC
    mcp_request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": f"tools/call",
        "params": {"name": tool_name, "arguments": tool_input}
    }
    
    # 2. Send to the server's stdin
    mcp_server_process.stdin.write(json.dumps(mcp_request) + "\n")
    mcp_server_process.stdin.flush()
    
    # 3. Read the response from stdout
    response_str = mcp_server_process.stdout.readline()
    return json.loads(response_str)

# Start a conversation with Claude
user_message = "Find me documents about React state management"
message = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    messages=[{"role": "user", "content": user_message}],
    tools=mcp_tools_definition, # Present the tools to Claude
).content

# Claude requests to use the vector_search tool
tool_use = next(block for block in message if block.type == "tool_use")
tool_name = tool_use.name
tool_input = tool_use.input

# Call the tool via the MCP server
tool_result = call_mcp_tool(tool_name, tool_input)

# Send the result back to Claude to get a natural language answer
final_response = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": user_message},
        {"role": "assistant", "content": message},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": json.dumps(tool_result),
                }
            ],
        },
    ],
    tools=mcp_tools_definition,
).content[0].text

print(final_response)
# Expected output: "I found a few documents related to React state management..."

This workflow allows Claude to intelligently use your database as a knowledge source to answer user queries with up-to-date, relevant information.

🏗️ Development

If you want to modify or contribute to the server:

1. Clone the repository:

   git clone https://github.com/yusuf/mcp-pgvector-server.git
   cd mcp-pgvector-server

2. Install dependencies:

   npm install

3. Run the development server: Create a .env file with your configuration and run:

   npm run dev

   This will start the server with nodemon, which automatically restarts on file changes.

📦 Publishing to NPM

To publish your own version:

1. Update the version in package.json.
2. Run npm publish.

📄 License

This project is licensed under the MIT License.