Mixedbread MCP Server

Connect your Mixedbread vector stores to any MCP-compatible client through the Model Context Protocol. Our MCP allows you to manage and search your vector store documents in natural language. Reduce your search time and improve your code output quality through rag in coding agents like claude code and cursor.

Overview

The Mixedbread MCP Server allows you to:

• Create and manage vector stores for your documents
• Upload and process files with automated chunking and embedding
• Retrieve specific files and their contents
• Build AI-native search experiences directly in any MCP-Client

Available Tools

vector_store_create

Create a new vector store to organize your documents.

• Input: Vector store name
• Returns: Vector store details

vector_store_list

List all vector stores in your account.

• Input: Optional search query to filter vector stores.
• Returns: Array of vector stores with metadata

vector_store_retrieve

Get detailed information about a specific vector store.

• Input: Vector store ID
• Returns: Store details including file count and settings

vector_store_delete

Delete a vector store and all its contents.

• Input: Vector store ID
• Returns: Deletion confirmation

vector_store_upload

Upload files to a vector store for processing and indexing.

• Input: Vector store ID, file paths
• Returns: Upload status and processed file information

vector_store_search

Search for specific chunks within a vector store.

• Input: Vector store ID, search query, optional filters
• Returns: Relevant file chunks, scores, metadata

vector_store_file_search

Search for specific files within a vector store.

• Input: Vector store ID, search query, optional filters
• Returns: Relevant files, scores, file chunks, metadata

vector_store_file_retrieve

Retrieve details about a specific file in a vector store.

• Input: Vector store ID, file ID
• Returns: File metadata and content access

Prerequisites

• Node.js: Version 20 or higher
• Mixedbread API Key: Get yours at platform.mixedbread.com
• MCP Client: Claude Desktop or another MCP-compatible client
• Optional: @modelcontextprotocol/server-filesystem for local file uploads

Installation

NPM Global Install (Recommended)

npm install -g @mixedbread/mcp

Test Installation

npx @mixedbread/mcp

You should see the MCP server start message if installed correctly.

Configuration

Claude Desktop Setup

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the Mixedbread MCP server configuration:

{
  "mcpServers": {
    "mixedbread": {
      "command": "npx",
      "args": ["-y", "@mixedbread/mcp"],
      "env": {
        "MXBAI_API_KEY": "mxb_your_api_key_here"
      }
    }
  }
}

With Filesystem Server (for file uploads)

To upload local files, also configure the filesystem MCP server:

{
  "mcpServers": {
    "mixedbread": {
      "command": "npx",
      "args": ["-y", "@mixedbread/mcp"],
      "env": {
        "MXBAI_API_KEY": "mxb_your_api_key_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/documents"
      ]
    }
  }
}

Environment Variables

• MXBAI_API_KEY: Your Mixedbread API key (required)

Usage Examples

Once configured, you can interact with your vector stores using natural language in Claude Desktop:

Creating a Vector Store

"Create a new vector store called 'Product Documentation'"

Uploading Documents

"Upload all markdown files from the docs folder to my Product Documentation store"

Searching Content

"Search for information about authentication in the Product Documentation store"

Managing Stores

"List all my vector stores"

Advanced Queries

"Find all files in the Product Documentation store that mention API endpoints"

Development

Building from Source

# Clone the repository
git clone https://github.com/mixedbread-ai/openbread.git
cd openbread/packages/mcp

# Install dependencies
npm install

# Build the server
npm run build

# Run in development mode
npm run dev

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Security

API Key Management

• Store API keys securely in environment variables
• Never commit API keys to version control
• Use separate API keys for development and production
• Rotate keys regularly

Troubleshooting

Common Issues

"API key not found" error

• Verify your API key starts with mxb_
• Check the key is correctly set in Claude Desktop config
• Ensure there are no extra spaces or quotes around the key

"Cannot connect to Mixedbread API"

• Check your internet connection
• Verify the API endpoint is accessible
• Ensure your firewall allows outbound HTTPS connections

"File upload failed"

• Confirm the filesystem MCP server is configured
• Check file paths are within allowed directories

Tools not appearing in Claude

• Restart Claude Desktop after configuration changes
• Check the MCP server is running (test with npx @mixedbread/mcp)
• Review Claude Desktop logs for errors

Links & Resources

• Mixedbread Documentation: mixedbread.com/docs
• MCP Documentation: mixedbread.com/mcp
• API Reference: mixedbread.com/api-reference
• Model Context Protocol: modelcontextprotocol.io
• GitHub Issues: github.com/mixedbread-ai/openbread/issues
• Support: [email protected]

License

This project is licensed under the Apache License 2.0.

🍞 Baked with love by Mixedbread