Pinecone

Servidor de Protocolo de Contexto de Modelo (MCP) Pinecone para Claude Desktop.

Leia e escreva em um índice Pinecone.

Componentes

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

Recursos

O servidor implementa a capacidade de ler e escrever em um índice Pinecone.

Ferramentas

• semantic-search: Buscar registros no índice Pinecone.
• read-document: Ler um documento do índice Pinecone.
• list-documents: Listar todos os documentos no índice Pinecone.
• pinecone-stats: Obter estatísticas sobre o índice Pinecone, incluindo o número de registros, dimensões e namespaces.
• process-document: Processar um documento em partes e inseri-las no índice Pinecone. Isso executa as etapas gerais de divisão em partes, incorporação (embedding) e inserção.

Nota: as incorporações são geradas por meio da API de inferência do Pinecone e a divisão em partes é feita com um divisor baseado em tokens. Escrito copiando bastante do langchain e depurando com Claude.

Início Rápido

Instalação via Smithery

Para instalar o Pinecone MCP Server para Claude Desktop automaticamente via Smithery:

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

Instalar o servidor

Recomenda-se usar uv para instalar o servidor localmente para Claude.

uvx install mcp-pinecone

OU

uv pip install mcp-pinecone

Adicione sua configuração conforme descrito abaixo.

Claude Desktop

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

Nota: Você pode precisar usar o caminho direto para uv. Use which uv para encontrar o caminho.

Configuração de Servidores em Desenvolvimento/Não Publicados

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

Configuração de Servidores Publicados

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

Cadastre-se no Pinecone

Você pode se cadastrar para uma conta Pinecone aqui.

Obter uma chave de API

Crie um novo índice no Pinecone, substituindo {your-index-name} e obtenha uma chave de API no painel do Pinecone, substituindo {your-secret-api-key} na configuração.

Desenvolvimento

Construção e Publicação

Para preparar o pacote para distribuição:

1. Sincronize as dependências e atualize o arquivo de bloqueio:

uv sync

2. Construa as distribuições do pacote:

uv build

Isso criará distribuições de origem e wheel no diretório dist/.

3. Publique no PyPI:

uv publish

Nota: Você precisará definir as credenciais do PyPI por meio de variáveis de ambiente ou flags de comando:

• Token: --token ou UV_PUBLISH_TOKEN
• Ou nome de usuário/senha: --username/UV_PUBLISH_USERNAME e --password/UV_PUBLISH_PASSWORD

Depuração

Como os servidores MCP são executados via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente usar o MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

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

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depurar.

Licença

Este projeto está licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Código Fonte

O código-fonte está disponível no GitHub.

Contribuição

Envie suas ideias e feedback para mim no Bluesky ou abrindo uma issue.