📌Overview

Purpose: To provide a seamless framework for reading and writing to a Pinecone index for applications such as Claude Desktop.

Overview: The Pinecone Model Context Protocol Server facilitates efficient interactions with a Pinecone index, enabling users to conduct operations like semantic search, document reading, and statistics retrieval. This server is integral for applications needing quick access to large datasets through a robust indexing system.

Key Features:

Semantic Search: Allows users to perform searches within the Pinecone index, retrieving records based on semantic similarity.
Document Management: Features tools to read individual documents, list all documents, and process new documents into chunks for upsert into the index, ensuring efficient and organized data management.

Pinecone Model Context Protocol Server for Claude Desktop

Read and write to a Pinecone index.

Components

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

Resources

The server enables reading and writing to a Pinecone index.

Tools

semantic-search: Search for records in the Pinecone index.
read-document: Read a document from the Pinecone index.
list-documents: List all documents in the Pinecone index.
pinecone-stats: Get stats about the Pinecone index, including the number of records, dimensions, and namespaces.
process-document: Process a document into chunks and upsert them into the Pinecone index, performing chunking, embedding, and upserting.

Note: Embeddings are generated via Pinecone's inference API and chunking is done with a token-based chunker.

Quickstart

Installing via Smithery

To install Pinecone MCP Server for Claude Desktop automatically via Smithery:

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

Install the server

We recommend using uv to install the server locally for Claude.

uvx install mcp-pinecone

uv pip install mcp-pinecone

Add your config as described below.

Claude Desktop Config Locations

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

You might need to use the direct path to uv. Use which uv to find the path.

Configuration

Development/Unpublished Servers

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

Published Servers

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

Pinecone Account Setup

Create a new index in Pinecone and obtain your API key from the Pinecone dashboard. Replace {your-index-name} and {your-secret-api-key} in the configuration above accordingly.

Development

Building and Publishing

To prepare the package for distribution:

Sync dependencies and update lockfile:
```
uv sync
```
Build package distributions:
```
uv build
```
This creates source and wheel distributions in the dist/ directory.
Publish to PyPI:
```
uv publish
```

You need to set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best experience, use the MCP Inspector tool.

Launch the MCP Inspector with npm:

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

The Inspector will provide a URL to open in your browser for debugging.

License

This project is licensed under the MIT License.

Source Code

The source code is available on GitHub: https://github.com/sirmews/mcp-pinecone

Contributing

Send your ideas and feedback via Bluesky: https://bsky.app/profile/perfectlycromulent.bsky.social or by opening an issue.