Pinecone MCP Server

MCP server for Pinecone vector database. Store and search embeddings for similarity search, semantic search, and RAG (Retrieval Augmented Generation) applications.

Features

• Index Management: Create, list, describe, and delete vector indexes

• Vector Operations: Upsert, query, fetch, update, and delete vectors

• Similarity Search: Find similar vectors with cosine, euclidean, or dot product metrics

• Metadata Filtering: Hybrid search with metadata filters

• Namespaces: Data isolation for multi-tenancy

• Collections: Create backups from indexes

• Statistics: Get vector counts and index stats

Setup

Prerequisites

• Pinecone account

• API key and environment name

Environment Variables

• PINECONE_API_KEY (required): Your Pinecone API key

• PINECONE_ENVIRONMENT (required): Your Pinecone environment

How to get credentials:

1. Go to app.pinecone.io

2. Sign up or log in

3. Navigate to API Keys section

4. Copy your API key

5. Note your environment (e.g., us-west1-gcp, us-east-1-aws)

6. Store as PINECONE_API_KEY and PINECONE_ENVIRONMENT

Index Types

Serverless (Recommended)

• Pay per usage

• Auto-scaling

• No infrastructure management

• Available regions: AWS (us-east-1, us-west-2), GCP (us-central1, us-west1), Azure (eastus)

Pod-based

• Fixed capacity

• Dedicated resources

• More control over performance

• Higher cost

Vector Dimensions

Match your embedding model:

• OpenAI text-embedding-ada-002: 1536 dimensions

• OpenAI text-embedding-3-small: 1536 dimensions

• OpenAI text-embedding-3-large: 3072 dimensions

• sentence-transformers/all-MiniLM-L6-v2: 384 dimensions

• sentence-transformers/all-mpnet-base-v2: 768 dimensions

Distance Metrics

• cosine - Cosine similarity (recommended for most use cases)

• euclidean - Euclidean distance

• dotproduct - Dot product similarity

Available Tools

Index Management

list_indexes

List all indexes in the project.

Example:

indexes = await list_indexes()

create_index

Create a new vector index.

Parameters:

• name (string, required): Index name

• dimension (int, required): Vector dimension

• metric (string, optional): Distance metric (default: 'cosine')

• spec_type (string, optional): 'serverless' or 'pod' (default: 'serverless')

• cloud (string, optional): 'aws', 'gcp', or 'azure' (default: 'aws')

• region (string, optional): Region (default: 'us-east-1')

Example:

index = await create_index(
    name="my-index",
    dimension=1536,  # OpenAI embeddings
    metric="cosine",
    spec_type="serverless",
    cloud="aws",
    region="us-east-1"
)

describe_index

Get index configuration and status.

Example:

info = await describe_index(index_name="my-index")

delete_index

Delete an index.

Example:

result = await delete_index(index_name="my-index")

Vector Operations

upsert_vectors

Insert or update vectors with metadata.

Parameters:

• index_name (string, required): Index name

• vectors (list, required): List of vector objects

• namespace (string, optional): Namespace (default: "")

Vector format:

{
    "id": "vec1",
    "values": [0.1, 0.2, 0.3, ...],  # Must match index dimension
    "metadata": {"key": "value"}  # Optional
}

Example:

result = await upsert_vectors(
    index_name="my-index",
    vectors=[
        {
            "id": "doc1",
            "values": [0.1, 0.2, ...],  # 1536 dimensions
            "metadata": {
                "title": "Document 1",
                "category": "tech",
                "year": 2024
            }
        },
        {
            "id": "doc2",
            "values": [0.3, 0.4, ...],
            "metadata": {
                "title": "Document 2",
                "category": "science"
            }
        }
    ],
    namespace="production"
)

query_vectors

Query similar vectors.

Parameters:

• index_name (string, required): Index name

• vector (list, optional): Query vector (use this OR id)

• id (string, optional): Vector ID to use as query (use this OR vector)

• top_k (int, optional): Number of results (default: 10)

• namespace (string, optional): Namespace (default: "")

• include_values (bool, optional): Include vectors (default: False)

• include_metadata (bool, optional): Include metadata (default: True)

• filter (dict, optional): Metadata filter

Example:

# Query by vector
results = await query_vectors(
    index_name="my-index",
    vector=[0.1, 0.2, ...],  # Your query embedding
    top_k=5,
    filter={"category": {"$eq": "tech"}, "year": {"$gte": 2023}},
    include_metadata=True
)

# Query by existing vector ID
results = await query_vectors(
    index_name="my-index",
    id="doc1",
    top_k=5
)

Response:

{
  "matches": [
    {
      "id": "doc1",
      "score": 0.95,
      "metadata": {"title": "Document 1", "category": "tech"}
    }
  ]
}

fetch_vectors

Fetch vectors by IDs.

Example:

vectors = await fetch_vectors(
    index_name="my-index",
    ids=["doc1", "doc2", "doc3"],
    namespace="production"
)

update_vector

Update vector values or metadata.

Example:

# Update values
result = await update_vector(
    index_name="my-index",
    id="doc1",
    values=[0.5, 0.6, ...]
)

# Update metadata
result = await update_vector(
    index_name="my-index",
    id="doc1",
    set_metadata={"category": "updated", "year": 2025}
)

delete_vectors

Delete vectors.

Example:

# Delete by IDs
result = await delete_vectors(
    index_name="my-index",
    ids=["doc1", "doc2"]
)

# Delete by filter
result = await delete_vectors(
    index_name="my-index",
    filter={"year": {"$lt": 2020}}
)

# Delete all in namespace
result = await delete_vectors(
    index_name="my-index",
    delete_all=True,
    namespace="test"
)

Statistics & Utility

describe_index_stats

Get index statistics.

Example:

stats = await describe_index_stats(index_name="my-index")
# Returns: dimension, totalVectorCount, indexFullness, namespaces

list_vector_ids

List all vector IDs.

Example:

ids = await list_vector_ids(
    index_name="my-index",
    namespace="production",
    prefix="doc",
    limit=100
)

create_collection

Create a collection (backup) from an index.

Example:

collection = await create_collection(
    name="my-backup",
    source_index="my-index"
)

Namespaces

Namespaces provide data isolation within an index:

# Production data
await upsert_vectors(index_name="my-index", vectors=[...], namespace="prod")

# Test data
await upsert_vectors(index_name="my-index", vectors=[...], namespace="test")

# Query only production
results = await query_vectors(index_name="my-index", vector=[...], namespace="prod")

Metadata Filtering

Filter vectors during queries using metadata:

Operators:

• $eq - Equal

• $ne - Not equal

• $gt - Greater than

• $gte - Greater than or equal

• $lt - Less than

• $lte - Less than or equal

• $in - In array

• $nin - Not in array

Examples:

# Simple filter
filter={"category": {"$eq": "tech"}}

# Range filter
filter={"year": {"$gte": 2020, "$lte": 2024}}

# Multiple conditions
filter={
    "$and": [
        {"category": {"$eq": "tech"}},
        {"year": {"$gte": 2020}}
    ]
}

# OR condition
filter={
    "$or": [
        {"category": {"$eq": "tech"}},
        {"category": {"$eq": "science"}}
    ]
}

# In array
filter={"category": {"$in": ["tech", "science", "engineering"]}}

RAG Example with OpenAI

import openai

# 1. Generate embedding
response = openai.Embedding.create(
    input="What is machine learning?",
    model="text-embedding-ada-002"
)
query_embedding = response['data'][0]['embedding']

# 2. Query Pinecone
results = await query_vectors(
    index_name="knowledge-base",
    vector=query_embedding,
    top_k=3,
    include_metadata=True
)

# 3. Get context from results
context = "\n".join([match['metadata']['text'] for match in results['matches']])

# 4. Generate answer with context
answer = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": f"Answer based on this context:\n{context}"},
        {"role": "user", "content": "What is machine learning?"}
    ]
)

Rate Limits

Free Tier (Starter)

• 100,000 operations/month

• 1 pod/index

• 100 indexes max

Paid Tiers

• Standard: $70/month, unlimited operations

• Enterprise: Custom pricing, dedicated support

Best Practices

1. Match dimensions: Ensure vector dimensions match index

2. Use namespaces: Separate prod/test/dev data

3. Add metadata: Enable hybrid search and filtering

4. Batch upserts: Insert multiple vectors per request

5. Use serverless: For most applications (cost-effective)

6. Monitor usage: Track vector count and operations

7. Create backups: Use collections for important data

8. Optimize queries: Use appropriate top_k values

Common Use Cases

• Semantic Search: Find similar documents or products

• RAG: Retrieval for LLM context

• Recommendation Systems: Similar item recommendations

• Duplicate Detection: Find near-duplicate content

• Anomaly Detection: Identify outliers

• Image Search: Visual similarity search

• Chatbot Memory: Store conversation context

Error Handling

Common errors:

• 401 Unauthorized: Invalid API key

• 404 Not Found: Index or vector not found

• 400 Bad Request: Invalid dimensions or parameters

• 429 Too Many Requests: Rate limit exceeded

• 503 Service Unavailable: Pinecone service issue

API Documentation

• Pinecone Documentation

• API Reference

• Python SDK

• Serverless Indexes

• Metadata Filtering

Support

• Pinecone Community

• Discord

• Support

• Status Page