Skip to main content

Read and write to Pinecone from Claude Desktop with Model Context Protocol.

Project description

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]
            UpsertDoc[upsert-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 implements the ability to read and write to a Pinecone index.

Tools

  • semantic-search: Search for records in the Pinecone index.
  • read-document: Read a document from the Pinecone index.
  • upsert-document: Upsert a document into the Pinecone index.

Note: embeddings are generated via Pinecone's inference API.

Quickstart

Install the server

Recommend using uv to install the server locally for Claude.

uvx install mcp-pinecone

OR

uv pip install mcp-pinecone

Add your config as described below.

Claude Desktop

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

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

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"
    ]
  }
}

Development

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:
uv sync
  1. Build package distributions:
uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:
uv publish

Note: You'll 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 debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

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

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Source Code

The source code is available on GitHub.

Contributing

Send your ideas and feedback to me on Bluesky or by opening an issue.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_pinecone-0.1.3.tar.gz (24.8 kB view details)

Uploaded Source

Built Distribution

mcp_pinecone-0.1.3-py3-none-any.whl (11.3 kB view details)

Uploaded Python 3

File details

Details for the file mcp_pinecone-0.1.3.tar.gz.

File metadata

  • Download URL: mcp_pinecone-0.1.3.tar.gz
  • Upload date:
  • Size: 24.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.5.7

File hashes

Hashes for mcp_pinecone-0.1.3.tar.gz
Algorithm Hash digest
SHA256 d54fbf76bde197ee86e78184c1bab9b0c3d0881608a297616cafe071eca1e7e7
MD5 4f28c8339ac893874296a16b92ca64ff
BLAKE2b-256 5497a6b3fd41d27fd04743a71feabda4c3e2485e29dc2acad4bc0846bbe26b8b

See more details on using hashes here.

File details

Details for the file mcp_pinecone-0.1.3-py3-none-any.whl.

File metadata

File hashes

Hashes for mcp_pinecone-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 e9b80a64650fb2c30ee55c994856a40d95bed8cb4d49da5b70b86aa4f2206eb3
MD5 abf5ff7e3e866ac753f8da687f91d587
BLAKE2b-256 ae8c91fadb24de784fdbbf460dd09547d857b54945bdfe34e031772cc4338207

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page