Pinecone Model Context Protocol Server for Claude Desktop.

1# Pinecone Model Context Protocol Server for Claude Desktop.
2 
3[![smithery badge](https://smithery.ai/badge/mcp-pinecone)](https://smithery.ai/server/mcp-pinecone)
4 
5[![PyPI - Downloads](https://img.shields.io/pypi/dd/mcp-pinecone?style=flat)](https://pypi.org/project/mcp-pinecone/)
6 
7Read and write to a Pinecone index.
8 
9 
10## Components
11 
12```mermaid
13flowchart TB
14    subgraph Client["MCP Client (e.g., Claude Desktop)"]
15        UI[User Interface]
16    end
17 
18    subgraph MCPServer["MCP Server (pinecone-mcp)"]
19        Server[Server Class]
20        
21        subgraph Handlers["Request Handlers"]
22            ListRes[list_resources]
23            ReadRes[read_resource]
24            ListTools[list_tools]
25            CallTool[call_tool]
26            GetPrompt[get_prompt]
27            ListPrompts[list_prompts]
28        end
29        
30        subgraph Tools["Implemented Tools"]
31            SemSearch[semantic-search]
32            ReadDoc[read-document]
33            ListDocs[list-documents]
34            PineconeStats[pinecone-stats]
35            ProcessDoc[process-document]
36        end
37    end
38 
39    subgraph PineconeService["Pinecone Service"]
40        PC[Pinecone Client]
41        subgraph PineconeFunctions["Pinecone Operations"]
42            Search[search_records]
43            Upsert[upsert_records]
44            Fetch[fetch_records]
45            List[list_records]
46            Embed[generate_embeddings]
47        end
48        Index[(Pinecone Index)]
49    end
50 
51    %% Connections
52    UI --> Server
53    Server --> Handlers
54    
55    ListTools --> Tools
56    CallTool --> Tools
57    
58    Tools --> PC
59    PC --> PineconeFunctions
60    PineconeFunctions --> Index
61    
62    %% Data flow for semantic search
63    SemSearch --> Search
64    Search --> Embed
65    Embed --> Index
66    
67    %% Data flow for document operations
68    UpsertDoc --> Upsert
69    ReadDoc --> Fetch
70    ListRes --> List
71 
72    classDef primary fill:#2563eb,stroke:#1d4ed8,color:white
73    classDef secondary fill:#4b5563,stroke:#374151,color:white
74    classDef storage fill:#059669,stroke:#047857,color:white
75    
76    class Server,PC primary
77    class Tools,Handlers secondary
78    class Index storage
79```
80 
81### Resources
82 
83The server implements the ability to read and write to a Pinecone index.
84 
85### Tools
86 
87- `semantic-search`: Search for records in the Pinecone index.
88- `read-document`: Read a document from the Pinecone index.
89- `list-documents`: List all documents in the Pinecone index.
90- `pinecone-stats`: Get stats about the Pinecone index, including the number of records, dimensions, and namespaces.
91- `process-document`: Process a document into chunks and upsert them into the Pinecone index. This performs the overall steps of chunking, embedding, and upserting.
92 
93Note: embeddings are generated via Pinecone's inference API and chunking is done with a token-based chunker. Written by copying a lot from langchain and debugging with Claude.
94## Quickstart
95 
96### Installing via Smithery
97 
98To install Pinecone MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-pinecone):
99 
100```bash
101npx -y @smithery/cli install mcp-pinecone --client claude
102```
103 
104### Install the server
105 
106Recommend using [uv](https://docs.astral.sh/uv/getting-started/installation/) to install the server locally for Claude.
107 
108```
109uvx install mcp-pinecone
110```
111OR
112```
113uv pip install mcp-pinecone
114```
115 
116Add your config as described below.
117 
118#### Claude Desktop
119 
120On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
121On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
122 
123Note: You might need to use the direct path to `uv`. Use `which uv` to find the path.
124 
125 
126__Development/Unpublished Servers Configuration__
127  
128```json
129"mcpServers": {
130  "mcp-pinecone": {
131    "command": "uv",
132    "args": [
133      "--directory",
134      "{project_dir}",
135      "run",
136      "mcp-pinecone"
137    ]
138  }
139}
140```
141 
142 
143__Published Servers Configuration__
144  
145```json
146"mcpServers": {
147  "mcp-pinecone": {
148    "command": "uvx",
149    "args": [
150      "--index-name",
151      "{your-index-name}",
152      "--api-key",
153      "{your-secret-api-key}",
154      "mcp-pinecone"
155    ]
156  }
157}
158```
159 
160#### Sign up to Pinecone
161 
162You can sign up for a Pinecone account [here](https://www.pinecone.io/).
163 
164#### Get an API key
165 
166Create a new index in Pinecone, replacing `{your-index-name}` and get an API key from the Pinecone dashboard, replacing `{your-secret-api-key}` in the config.
167 
168## Development
169 
170### Building and Publishing
171 
172To prepare the package for distribution:
173 
1741. Sync dependencies and update lockfile:
175```bash
176uv sync
177```
178 
1792. Build package distributions:
180```bash
181uv build
182```
183 
184This will create source and wheel distributions in the `dist/` directory.
185 
1863. Publish to PyPI:
187```bash
188uv publish
189```
190 
191Note: You'll need to set PyPI credentials via environment variables or command flags:
192- Token: `--token` or `UV_PUBLISH_TOKEN`
193- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
194 
195### Debugging
196 
197Since MCP servers run over stdio, debugging can be challenging. For the best debugging
198experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
199 
200 
201You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
202 
203```bash
204npx @modelcontextprotocol/inspector uv --directory {project_dir} run mcp-pinecone
205```
206 
207 
208Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
209 
210## License
211 
212This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
213 
214## Source Code
215 
216The source code is available on [GitHub](https://github.com/sirmews/mcp-pinecone).
217 
218## Contributing
219 
220Send your ideas and feedback to me on [Bluesky](https://bsky.app/profile/perfectlycromulent.bsky.social) or by opening an issue.
221