Pinecone Read-Only MCP

A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.

Features

• Hybrid Search: Combines dense and sparse embeddings for superior recall
• Semantic Reranking: Uses BGE reranker model for improved precision
• Dynamic Namespace Discovery: Automatically discovers available namespaces in your Pinecone index
• Metadata Filtering: Supports optional metadata filters for refined searches
• Fast & Optimized: Lazy initialization, connection pooling, and efficient result merging
• Production Ready: Input validation, error handling, and configurable logging

Installation

In a uv managed python project, add to dependencies by:

uv add pinecone-read-only-mcp

Alternatively, for projects using pip for dependencies:

pip install pinecone-read-only-mcp

To run the server inside your project:

uv run pinecone-read-only-mcp --api-key YOUR_PINECONE_API_KEY

Or to run it globally in isolated environment:

uvx pinecone-read-only-mcp --api-key YOUR_PINECONE_API_KEY

To install directly from the source:

git clone https://github.com/iTinkerBell/pinecone-read-only-mcp.git
cd pinecone-read-only-mcp
pip install -e .

Configuration

The server requires a Pinecone API key and supports the following configuration options:

Environment Variables

Variable	Required	Default	Description
PINECONE_API_KEY	Yes	-	Your Pinecone API key
PINECONE_INDEX_NAME	No	rag-hybrid	Pinecone index name
PINECONE_RERANK_MODEL	No	bge-reranker-v2-m3	Reranking model
PINECONE_READ_ONLY_MCP_LOG_LEVEL	No	INFO	Logging level

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pinecone-search": {
      "command": "uvx",
      "args": ["pinecone-read-only-mcp"],
      "env": {
        "PINECONE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or with explicit options:

{
  "mcpServers": {
    "pinecone-search": {
      "command": "uvx",
      "args": [
        "pinecone-read-only-mcp",
        "--api-key", "your-api-key-here",
        "--index-name", "your-index-name",
        "--rerank-model", "bge-reranker-v2-m3"
      ]
    }
  }
}

Usage

Command Line

The server can be run in two modes:

Standard I/O mode (default):

pinecone-read-only-mcp --api-key YOUR_API_KEY

SSE transport mode (for web applications):

pinecone-read-only-mcp --api-key YOUR_API_KEY --transport sse --port 8000

Available Options

--api-key TEXT        Pinecone API key (or set PINECONE_API_KEY env var)
--index-name TEXT     Pinecone index name [default: rag-hybrid]
--rerank-model TEXT   Reranking model [default: bge-reranker-v2-m3]
--transport [stdio|sse]  Transport type [default: stdio]
--port INTEGER        Port for SSE transport [default: 8000]
--log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]  Logging level [default: INFO]

API Documentation

The server exposes the following tools via MCP:

list_namespaces

Discovers and lists all available namespaces in the configured Pinecone index.

Parameters: None

Returns: JSON object with available namespaces and count

Example response:

{
  "status": "success",
  "namespaces": ["namespace1", "namespace2", "namespace3"],
  "count": 3
}

query

Performs hybrid semantic search over the specified namespace in the Pinecone index.

Parameters:

Parameter	Type	Required	Default	Description
query_text	string	Yes	-	Search query text
namespace	string	Yes	-	Namespace to search (use list_namespaces to discover)
top_k	integer	No	10	Number of results (1-100)
use_reranking	boolean	No	true	Enable semantic reranking

Returns: JSON object with search results including content, relevance scores, and metadata

Example response:

{
  "status": "success",
  "query": "your search query",
  "namespace": "namespace1",
  "result_count": 10,
  "results": [
    {
      "paper_number": "DOC-001",
      "title": "Document Title",
      "author": "Author Name",
      "url": "https://example.com/doc",
      "content": "Document content preview...",
      "score": 0.9234,
      "reranked": true
    }
  ]
}

How It Works

1. Namespace Discovery: The list_namespaces tool queries your Pinecone index stats to discover available namespaces
2. Hybrid Search: When querying, the tool searches both dense and sparse indexes in parallel
3. Result Merging: Results from both indexes are merged and deduplicated
4. Reranking (optional): The merged results are reranked using a semantic reranker for improved relevance

Dependencies

• anyio (>=4.5.0)
• click (>=8.1.8)
• mcp (>=1.6.0)
• pinecone (>=5.0.0)
• python-dotenv (>=1.0.0)
• pydantic (>=2.0.0)

Development

Setup Development Environment

git clone https://github.com/iTinkerBell/pinecone-read-only-mcp.git
cd pinecone-read-only-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Code Quality

# Run linting
uv run ruff check .

# Run formatting check
uv run ruff format --check .

# Run security checks
uv run bandit -r src/

Contribution Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

License

This project is licensed under the Boost Software License 1.0 - see the LICENSE file for details.

Authors

• Will Pak - cppalliance.org

Acknowledgements

This project uses Pinecone for vector storage and retrieval. The hybrid search approach combines dense embeddings with sparse BM25-style retrieval for optimal results.