Unleash the Power of Context: Pinecone MCP Server for Seamless LLM Integration

The Pinecone Model Context Protocol (MCP) Server bridges the gap between Large Language Models (LLMs) and your Pinecone vector database, enabling powerful AI applications with enhanced contextual awareness. This server, designed for seamless integration with clients like Claude Desktop, empowers you to build intelligent solutions that leverage the power of semantic search and document retrieval.

Architecture Overview

The following diagram illustrates the key components and data flow within the Pinecone MCP Server:

flowchart TB
    subgraph Client["MCP Client (e.g., Claude Desktop)"]
        UI[User Interface]
    end

    subgraph MCPServer["MCP Server (pinecone-mcp)"]
        Server[Server Class]
        
        subgraph Handlers["Request Handlers"]
            ListRes[list_resources]
            ReadRes[read_resource]
            ListTools[list_tools]
            CallTool[call_tool]
            GetPrompt[get_prompt]
            ListPrompts[list_prompts]
        end
        
        subgraph Tools["Implemented Tools"]
            SemSearch[semantic-search]
            ReadDoc[read-document]
            ListDocs[list-documents]
            PineconeStats[pinecone-stats]
            ProcessDoc[process-document]
        end
    end

    subgraph PineconeService["Pinecone Service"]
        PC[Pinecone Client]
        subgraph PineconeFunctions["Pinecone Operations"]
            Search[search_records]
            Upsert[upsert_records]
            Fetch[fetch_records]
            List[list_records]
            Embed[generate_embeddings]
        end
        Index[(Pinecone Index)]
    end

    %% Connections
    UI --> Server
    Server --> Handlers
    
    ListTools --> Tools
    CallTool --> Tools
    
    Tools --> PC
    PC --> PineconeFunctions
    PineconeFunctions --> Index
    
    %% Data flow for semantic search
    SemSearch --> Search
    Search --> Embed
    Embed --> Index
    
    %% Data flow for document operations
    UpsertDoc --> Upsert
    ReadDoc --> Fetch
    ListRes --> List

    classDef primary fill:#2563eb,stroke:#1d4ed8,color:white
    classDef secondary fill:#4b5563,stroke:#374151,color:white
    classDef storage fill:#059669,stroke:#047857,color:white
    
    class Server,PC primary
    class Tools,Handlers secondary
    class Index storage

Key Components:

• MCP Client: The application interacting with the server (e.g., Claude Desktop).
• MCP Server: The pinecone-mcp server, acting as the intermediary between the client and Pinecone.
• Request Handlers: Components that process specific requests from the client, such as listing resources, reading data, or calling tools.
• Tools: Pre-built functionalities that leverage the Pinecone service, including semantic search, document retrieval, and index statistics.
• Pinecone Service: The interface to the Pinecone vector database, handling operations like searching, upserting, and fetching records.
• Pinecone Index: Your Pinecone vector database, storing embeddings and metadata.

Core Functionalities

This server provides the following key functionalities:

• Resource Management: Enables reading and writing data to your Pinecone index.
• Semantic Search (semantic-search): Performs similarity searches within your Pinecone index, retrieving relevant information based on semantic meaning.
• Document Retrieval (read-document, list-documents): Allows you to retrieve specific documents or list all documents stored in your index.
• Index Statistics (pinecone-stats): Provides insights into your Pinecone index, including the number of records, dimensions, and namespaces.
• Document Processing (process-document): Facilitates the ingestion of documents into your Pinecone index by automatically chunking, embedding, and upserting the data. This leverages Pinecone's inference API for embedding generation and a token-based chunker for optimal performance.

Getting Started

Installation

1. Using Smithery (Recommended):

npx -y @smithery/cli install mcp-pinecone --client claude

2. Manual Installation with uv:

uvx install mcp-pinecone

OR

uv pip install mcp-pinecone

Configuration

1. Claude Desktop Configuration:

Locate the Claude Desktop configuration file:

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

2. Add Server Configuration:

Choose either the Development/Unpublished or Published Servers configuration based on your needs.

Development/Unpublished Servers Configuration:

"mcpServers": {
  "mcp-pinecone": {
    "command": "uv",
    "args": [
      "--directory",
      "{project_dir}",
      "run",
      "mcp-pinecone"
    ]
  }
}

Published Servers Configuration:

"mcpServers": {
  "mcp-pinecone": {
    "command": "uvx",
    "args": [
      "--index-name",
      "{your-index-name}",
      "--api-key",
      "{your-secret-api-key}",
      "mcp-pinecone"
    ]
  }
}

3. Pinecone Setup:

• Sign Up: Create a Pinecone account here.
• API Key and Index: Create a new index in Pinecone, replacing {your-index-name} in the configuration. Obtain your API key from the Pinecone dashboard and replace {your-secret-api-key} in the configuration.

Development and Contribution

Building and Publishing

1. Sync Dependencies:

   uv sync

2. Build Package Distributions:

   uv build

3. Publish to PyPI:

   uv publish

   Remember to configure your PyPI credentials using environment variables or command flags.

Debugging

Debugging MCP servers can be challenging due to their stdio-based communication. The MCP Inspector (https://github.com/modelcontextprotocol/inspector) is highly recommended for a streamlined debugging experience.

Launch the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory {project_dir} run mcp-pinecone

The Inspector will provide a URL to access the debugging interface in your browser.

Connect and Contribute

Your feedback and contributions are highly valued! Share your ideas and suggestions on Bluesky or by opening an issue on the GitHub repository.