@mixedbread/mcp-server

A TypeScript-based MCP (Model Context Protocol) server that provides comprehensive vector store capabilities using Mixedbread's SDK. This server exposes powerful tools for searching, managing, and interacting with vector stores directly from Claude Desktop and other MCP-compatible clients.

Installation

``bash
npm install -g @mixedbread/mcp-server
`

Quick Start

$3

- Node.js 20+
- Mixedbread API key from Mixedbread Dashboard

$3

`bash


Set your API key

export MIXEDBREAD_API_KEY="your_api_key_here"

Start the server

mcp-server

Or run directly with npx

npx @mixedbread/mcp-server
`

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

$3

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

`json
{
"mcpServers": {
"mixedbread": {
"command": "npx",
"args": ["@mixedbread/mcp-server"],
"env": {
"MIXEDBREAD_API_KEY": "your_api_key_here"
}
}
}
}
`

$3

Edit %APPDATA%\Claude\claude_desktop_config.json:

`json
{
"mcpServers": {
"mixedbread": {
"command": "npx",
"args": ["@mixedbread/mcp-server"],
"env": {
"MIXEDBREAD_API_KEY": "your_api_key_here"
}
}
}
}
`

$3

Edit ~/.config/Claude/claude_desktop_config.json:

`json
{
"mcpServers": {
"mixedbread": {
"command": "npx",
"args": ["@mixedbread/mcp-server"],
"env": {
"MIXEDBREAD_API_KEY": "your_api_key_here"
}
}
}
}
`

$3

For full functionality including file uploads, configure both the Mixedbread MCP server and the filesystem MCP server:

`json
{
"mcpServers": {
"mixedbread": {
"command": "npx",
"args": ["@mixedbread/mcp-server"],
"env": {
"MIXEDBREAD_API_KEY": "your_api_key_here"
}
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
}
}
}
`

Important Notes:

- Replace your_api_key_here with your actual Mixedbread API key
- Replace /path/to/allowed/directory with the directory path you want to allow file access from
- The filesystem MCP server is required for the upload tool to access local files
- Restart Claude Desktop after making these changes

Available Tools

$3

Search for relevant document chunks within vector stores.

Parameters:

- query (string): The search query text
- vector_store_identifiers (string[]): Array of vector store identifiers to search in
- top_k (number, default: 5): Number of top results to return
- filters (object, optional): Custom filters to apply
- file_ids (string[], optional): Specific file IDs to search within
- search_options (object, optional): Additional search configuration

$3

Search for relevant files within vector stores.

Parameters:

- query (string): The search query text
- vector_store_identifiers (string[]): Array of vector store identifiers to search in
- top_k (number, default: 5): Number of top results to return
- filters (object, optional): Custom filters to apply
- file_ids (string[], optional): Specific file IDs to search within
- search_options (object, optional): Advanced search options including:
- return_metadata (boolean): Whether to return metadata
- return_chunks (boolean, default: true): Whether to return chunks
- chunks_per_file (number): Number of chunks per file
- rerank (boolean): Whether to rerank results

$3

Get detailed information about a specific vector store.

Parameters:

- vector_store_id (string): The ID of the vector store to retrieve

$3

List all available vector stores with optional filtering and pagination.

Parameters:

- q (string, optional): Search query to filter vector stores
- limit (number, default: 20, max: 100): Maximum number of results
- after (string, optional): Pagination cursor for results after this ID
- before (string, optional): Pagination cursor for results before this ID

$3

Create a new vector store.

Parameters:

- name (string): Name of the vector store
- description (string, optional): Optional description

$3

Delete an existing vector store.

Parameters:

- vector_store_id (string): The ID of the vector store to delete

$3

Upload a file to a vector store with automatic MIME type detection.

Requirements:

- Requires the filesystem MCP server to be configured in Claude Desktop for file access (see example configuration above)

Parameters:

- vector_store_id (string): The ID of the target vector store
- file_path (string): Absolute path to the local file
- filename (string, optional): Custom filename (defaults to file basename)
- mime_type (string, optional): MIME type (auto-detected if not provided)

$3

Get detailed information about a specific file in a vector store.

Parameters:

- file_id (string): The ID of the file to retrieve
- vector_store_identifier (string): The identifier of the containing vector store

Example Usage in Claude

Once configured with Claude Desktop, you can use natural language to interact with your vector stores:

`
"Search for documents about machine learning in my research vector store"

"Create a new vector store called 'project-docs' for storing project documentation"

"Upload the file ~/Documents/report.pdf to the project-docs vector store"

"Show me all vector stores that contain 'legal' in their name"

"Find files similar to 'data analysis methodology' in my data-science store"
`

Authentication

The MCP server looks for your API key in this order:

1. MIXEDBREAD_API_KEY environment variable
2. Configuration file (if implemented in future versions)

Troubleshooting

$3

1. Server not starting in Claude Desktop

- Verify the package is installed globally: npm list -g @mixedbread/mcp-server
- Ensure the MIXEDBREAD_API_KEY is set correctly
- Check Claude Desktop logs for error messages

2. API key errors

- Verify your API key is valid at Mixedbread AI Dashboard
- Ensure no extra spaces or characters in the key
- API key must start with the correct prefix

3. Permission errors

- Make sure Claude Desktop has permission to execute npm/npx commands
- Verify your npm installation and global package permissions

4. Tools not appearing in Claude
- Restart Claude Desktop after configuration changes
- Check the Claude Desktop logs for error messages
- Verify JSON syntax in the configuration file
- Ensure the package is installed and accessible

Development

This MCP server is built on top of the @mixedbread/sdk and provides a bridge between MCP Clients and Mixedbread's vector store capabilities.

$3

#### Prerequisites

- Node.js 20+
- pnpm (package manager)
- Git

#### Setup

1. Clone the repository:

`bash
git clone https://github.com/mixedbread-ai/openbread.git
cd openbread/packages/mcp-server
`

2. Install dependencies:

`bash
pnpm install
`

3. Set up your API key:

`bash
export MIXEDBREAD_API_KEY=your_api_key_here
`

#### Development Workflow

1. Start development mode:

`bash
pnpm dev
`

2. Run tests:

`bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage
`

3. Lint and format:

`bash
pnpm lint # Check for issues
pnpm format # Format code
pnpm check-types # Type checking
`

4. Build:

`bash
pnpm build
``

Links

- Mixedbread AI
- Mixedbread CLI
- Model Context Protocol
- Claude Desktop