Pinecone Integration Module for Model Context Protocol (MCP)

This package provides the necessary server infrastructure to interface with a Pinecone vector database from an MCP-enabled application.

Architectural Components

mermaid flowchart TB subgraph ClientComponent["MCP Client (e.g., Claude Desktop)"] UI[User Interaction Layer] end

subgraph ServerComponent["MCP Server Implementation (pinecone-mcp)"]
    ServerCore[Core Server Logic]

    subgraph ProtocolHandlers["Request Handlers (MCP)"]
        HandleList[list_resources]
        HandleRead[read_resource]
        HandleToolList[list_tools]
        HandleToolCall[call_tool]
        HandleGetPrompt[get_prompt]
        HandleListPrompts[list_prompts]
    end

    subgraph ImplementedTools["Exposed Functionalities"]
        ToolSemSearch[vector-similarity-search]
        ToolReadVec[retrieve-vector-entry]
        ToolListVecs[enumerate-index-entries]
        ToolIndexMetrics[query-index-statistics]
        ToolIngestData[ingest-and-embed-document]
    end
end

subgraph ExternalService["Pinecone Cloud Service"]
    PCClient[Pinecone Client Library]
    subgraph VectorOps["Vector Database Operations"]
        OpSearch[search_operation]
        OpUpsert[upsert_operation]
        OpFetch[fetch_operation]
        OpList[list_operation]
        OpEmbed[embedding_generation]
    end
    IndexStore[(Target Pinecone Index)]
end

%% Connections
UI --> ServerCore
ServerCore --> ProtocolHandlers

HandleToolList --> ImplementedTools
HandleToolCall --> ImplementedTools

ImplementedTools --> PCClient
PCClient --> VectorOps
VectorOps --> IndexStore

%% Data flow example: Semantic Search
ToolSemSearch --> OpSearch
OpSearch --> OpEmbed
OpEmbed --> IndexStore

%% Data flow example: Document Management
ToolIngestData --> OpUpsert
ToolReadVec --> OpFetch
HandleList --> OpList

classDef primary fill:#10b981,stroke:#059669,color:white
classDef secondary fill:#f59e0b,stroke:#d97706,color:white
classDef storage fill:#3b82f6,stroke:#2563eb,color:white

class ServerCore,PCClient primary
class ImplementedTools,ProtocolHandlers secondary
class IndexStore storage

Supported Resources

This service endpoint enables granular control over reading data from and writing data to the designated Pinecone index.

Available Tools

• vector-similarity-search: Executes a similarity search query against the vector index.
• retrieve-vector-entry: Fetches a specific data record based on its ID from the index.
• enumerate-index-entries: Lists identifiers or metadata for entries residing within the index structure.
• query-index-statistics: Retrieves operational metrics for the index, such as vector count, dimensionality, and namespace distribution.
• ingest-and-embed-document: A comprehensive utility that segments documents, generates requisite embeddings (using Pinecone's inference API), and subsequently uploads the vectors to the index.

Note: Embedding computation relies on Pinecone's proprietary inference API, and document segmentation utilizes a token-aware chunking mechanism. Development involved substantial reference to LangChain implementations and iterative refinement via Claude.

Initial Setup Guide

Automated Installation via Smithery

Install the Pinecone MCP Server for Claude Desktop automatically using the Smithery orchestration tool:

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

Local Server Installation

We advise using the uv installer for managing local server dependencies for Claude integration.

uvx install mcp-pinecone

OR

uv pip install mcp-pinecone

Configuration details must then be appended to your client's settings file, as detailed below.

Client Configuration (e.g., Claude Desktop)

Locate the configuration file: On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Tip: If uv is not in your system PATH, you may need to provide the absolute path obtained via which uv.

For Development/Unpublished Server Deployment

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

For Published Server Deployment

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

Pinecone Account Registration

Establish your Pinecone account via this link: https://www.pinecone.io/.

Securing the API Credential

Provision a new index within Pinecone. Substitute {your-index-name} with the actual index name and acquire an API key from the Pinecone administrative panel to replace {your-secret-api-key} in the configuration block above.

Development Workflow

Construction and Dissemination

To prepare the package binaries for official release:

1. Synchronize all project dependencies and update the definitive lock file: bash uv sync

2. Generate the necessary package distributions (source and wheel formats): bash uv build

This action populates the dist/ directory.

1. Upload the package artifacts to the PyPI repository: bash uv publish

Note: PyPI credentials must be supplied either through environment variables (e.g., UV_PUBLISH_TOKEN) or command-line flags (--token, --username, --password).

Diagnostic Procedures

Troubleshooting MCP servers communicating over standard I/O can be complex. For the most effective debugging workflow, utilize the official MCP Inspector.

You can initiate the Inspector environment using npm (ensure Node.js is installed) with the following command:

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

Once launched, the Inspector will present a local URL. Navigating to this URL in a web browser initiates the debugging session.

Licensing

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for comprehensive legal details.

Source Repository

The complete source code is publicly accessible on GitHub.

Contributions

Feedback, feature proposals, or bug reports are welcome. Please connect with me on Bluesky or by raising an issue in the repository.