# Supavec MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants to fetch relevant embeddings and content from [Supavec](https://supavec.com).
## Features
- 🔍 **Fetch Embeddings**: Search and retrieve relevant content from Supavec files using embeddings
- 🤖 **AI Integration**: Works with Cursor, Claude, VS Code Copilot, and other MCP-compatible tools
- 🔑 **Flexible Authentication**: Support for both command-line arguments and environment variables
- ⚡ **Easy Setup**: One-command installation via npx
## Installation
### Quick Start with npx (Recommended)
No installation required! Use directly with npx:
```bash
npx @supavec/mcp-server --api-key your_api_key
```
### Global Installation
```bash
npm install -g @supavec/mcp-server
supavec-mcp --api-key your_api_key
```
## Configuration
### Cursor
Add to your `.cursor/mcp.json`:
```json
{
"mcpServers": {
"supavec": {
"command": "npx",
"args": [
"-y",
"@supavec/mcp-server@latest",
"--api-key",
"your_supavec_api_key"
]
}
}
}
```
### VS Code (Copilot)
Add to your `.vscode/mcp.json`:
```json
{
"servers": {
"supavec": {
"command": "npx",
"args": [
"-y",
"@supavec/mcp-server@latest",
"--api-key",
"your_supavec_api_key"
]
}
}
}
```
### Claude Desktop
Add to your Claude configuration:
```json
{
"mcpServers": {
"supavec": {
"command": "npx",
"args": [
"-y",
"@supavec/mcp-server@latest",
"--api-key",
"your_supavec_api_key"
]
}
}
}
```
### Environment Variables
Alternatively, set your API key as an environment variable:
```bash
export SUPAVEC_API_KEY=your_supavec_api_key
```
Then use in your MCP configuration without the `--api-key` argument:
```json
{
"mcpServers": {
"supavec": {
"command": "npx",
"args": ["-y", "@supavec/mcp-server@latest"]
}
}
}
```
## Authentication
### Get Your API Key
1. Visit [Supavec](https://supavec.com)
2. Sign up or log in to your account
3. Navigate to your API settings
4. Generate a new API key
### Usage Priority
The server checks for API keys in this order:
1. `--api-key` command line argument (highest priority)
2. `SUPAVEC_API_KEY` environment variable
## Available Tools
### `fetch-embeddings`
Fetch embeddings for a file by ID and query.
**Parameters:**
- `file_id` (string, required): ID of the file to get embeddings for
- `query` (string, required): Query to search for in the file
**Example:**
```
Ask your AI assistant: "Using Supavec, find information about 'authentication' in file abc123"
```
### `list-user-files`
List all files uploaded to Supavec for the current user.
**Parameters:**
- `limit` (number, optional): Number of files to fetch (default: 10)
- `offset` (number, optional): Offset for pagination (default: 0)
- `order_dir` (string, optional): Order direction for results - "asc" or "desc" (default: "desc")
**Example:**
```
Ask your AI assistant: "List my Supavec files" or "Show me the first 20 files from my Supavec account"
```
**Response includes:**
- File ID and name
- File type and creation date
- Team ID
- Pagination information
## Command Line Usage
### Help
```bash
supavec-mcp --help
```
### With API Key
```bash
supavec-mcp --api-key your_api_key_here
```
### With Environment Variable
```bash
export SUPAVEC_API_KEY=your_api_key_here
supavec-mcp
```
## Examples
### Using with Cursor
1. Configure Supavec MCP in `.cursor/mcp.json`
2. Open Cursor and start a new chat
3. Ask: *"Search for 'database setup' information in my Supavec file xyz789"*
4. The AI will use the Supavec MCP to fetch relevant content
### Using with Claude
1. Configure Supavec MCP in Claude settings
2. In a conversation, ask: *"Find documentation about API endpoints in file abc123"*
3. Claude will search your Supavec files and return relevant information
## Troubleshooting
### Common Issues
**"Error: Supavec API key is required"**
- Ensure you've provided an API key via `--api-key` or `SUPAVEC_API_KEY` environment variable
**"Failed to fetch data: status 401"**
- Your API key may be invalid or expired. Check your Supavec account settings
**"Failed to fetch data: status 404"**
- The file ID may not exist or you may not have access to it
### Debug Mode
Run with environment variables to see more details:
```bash
DEBUG=1 supavec-mcp --api-key your_key
```
## Development
### Requirements
- Node.js 16.0.0 or higher
- TypeScript
### Setup
```bash
git clone https://github.com/supavec/mcp-server.git
cd supavec-mcp-server
npm install
npm run build
```
### Testing
```bash
# Test with MCP Inspector
npm run inspector
# Test command line
npm run build
node build/index.js --help
```
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Commit your changes: `git commit -am 'Add feature'`
5. Push to the branch: `git push origin feature-name`
6. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) for details.
## Support
- 📚 [Supavec Documentation](https://supavec.com/docs)
- 🐛 [Report Issues](https://github.com/supavec/mcp-server/issues)
- 💬 [Community Support](https://supavec.com/community)
## Related
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Supavec Platform](https://supavec.com)
- [MCP Servers](https://github.com/modelcontextprotocol/servers)