README.md•5.66 kB
# Pinecone MCP Server
A Model Context Protocol server for Pinecone vector database operations.
This MCP server provides programmatic access to Pinecone vector database operations, enabling AI assistants to perform semantic search, manage vectors, and interact with your knowledge base through standardized MCP tools.
## Features
### Tools
#### 🔍 `query_vectors`
Perform semantic search on your Pinecone database
- **Input**: Text query, optional top_k and include_metadata parameters
- **Output**: JSON response with matching vectors and similarity scores
- **Use case**: Find relevant documents based on natural language queries
#### ➕ `upsert_vectors`
Add new documents to your vector database
- **Input**: Array of texts, optional metadata and IDs
- **Output**: Confirmation of successful vector insertion
- **Use case**: Index new documents or update existing knowledge base
#### 🗑️ `delete_vectors`
Remove vectors from your database
- **Input**: Array of vector IDs or delete_all flag
- **Output**: Confirmation of deletion operation
- **Use case**: Clean up outdated information or reset database
#### 📊 `get_index_stats`
Monitor your Pinecone database
- **Input**: None
- **Output**: Index statistics including vector count and configuration
- **Use case**: Track database usage and performance
## Quick Start
### Prerequisites
- Node.js 18+
- Pinecone account and API key
- OpenAI API key (for embeddings)
### Installation
1. **Clone and install dependencies:**
```bash
git clone <your-repo-url>
cd pinecone-mcp-server
npm install
```
2. **Build the server:**
```bash
npm run build
```
3. **Configure environment variables:**
```bash
export PINECONE_API_KEY="your_pinecone_key"
export OPENAI_API_KEY="your_openai_key"
export PINECONE_INDEX_NAME="your_index_name" # optional, defaults to "ad-assessor-docs"
```
4. **Run the server:**
```bash
node build/index.js
```
## MCP Configuration
### For Claude Desktop
Add to your MCP configuration file:
**MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"pinecone": {
"command": "node",
"args": ["/path/to/pinecone-mcp-server/build/index.js"],
"env": {
"PINECONE_API_KEY": "your_key_here",
"OPENAI_API_KEY": "your_key_here",
"PINECONE_INDEX_NAME": "your_index_name"
}
}
}
}
```
### For Cline (VSCode)
Add to: `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
```json
{
"mcpServers": {
"pinecone": {
"command": "node",
"args": ["C:\\path\\to\\pinecone-mcp-server\\build\\index.js"],
"env": {
"PINECONE_API_KEY": "your_key_here",
"OPENAI_API_KEY": "your_key_here",
"PINECONE_INDEX_NAME": "your_index_name"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Docker Deployment
### Build Docker Image
```bash
docker build -t pinecone-mcp .
```
### Run Container
```bash
docker run -e PINECONE_API_KEY=your_key \
-e OPENAI_API_KEY=your_key \
-e PINECONE_INDEX_NAME=your_index \
-p 3000:3000 \
pinecone-mcp
```
### Docker Compose
```yaml
version: '3.8'
services:
pinecone-mcp:
build: .
environment:
- PINECONE_API_KEY=your_key
- OPENAI_API_KEY=your_key
- PINECONE_INDEX_NAME=your_index
ports:
- "3000:3000"
```
## Development
### Project Structure
```
pinecone-server/
├── src/
│ └── index.ts # Main MCP server implementation
├── build/
│ └── index.js # Compiled JavaScript
├── Dockerfile # Docker configuration
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
### Development Commands
```bash
# Install dependencies
npm install
# Build for production
npm run build
# Development with auto-rebuild
npm run watch
# Debug with MCP Inspector
npm run inspector
```
### Adding New Tools
1. Define tool schema in `ListToolsRequestSchema` handler
2. Implement tool logic in `CallToolRequestSchema` handler
3. Update this README with new tool documentation
## API Keys Setup
### Pinecone
1. Sign up at [pinecone.io](https://pinecone.io)
2. Create a new project and index
3. Copy your API key from the dashboard
### OpenAI
1. Sign up at [platform.openai.com](https://platform.openai.com)
2. Navigate to API Keys section
3. Create a new secret key
## Troubleshooting
### Common Issues
**"Cannot find module" errors:**
- Ensure all dependencies are installed: `npm install`
- Check that the build completed successfully: `npm run build`
**Pinecone connection issues:**
- Verify API key is correct and has proper permissions
- Check that your index exists and is accessible
- Ensure your Pinecone environment/region is correct
**OpenAI API errors:**
- Confirm API key is valid and has credits
- Check rate limits and usage quotas
- Verify the model name is correct (text-embedding-ada-002)
### Debugging
Use the MCP Inspector for debugging:
```bash
npm run inspector
```
This provides a web interface to test your MCP server interactively.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Support
For issues and questions:
- Open an issue on GitHub
- Check the MCP documentation: https://modelcontextprotocol.io
- Review Pinecone documentation: https://docs.pinecone.io