meilisearch mcp

Local 2025-08-31 23:20:42 0

Server for interacting with [Meilisearch](https://www.meilisearch.com/) through LLM interfaces like Claude.

A Model Context Protocol (MCP) server for interacting with Meilisearch through LLM interfaces like Claude.

Features

Index and document management
Settings configuration and management
Task monitoring and API key management
Built-in logging and monitoring tools
Dynamic connection configuration to switch between Meilisearch instances
Smart search across single or multiple indices
This is a Python implementation, there is Typescript integration if you need to work with a Meilisearch MCP server within the browser

Installation

# Clone repository
git clone <repository_url>
cd meilisearch-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venvScriptsactivate
uv pip install -e .

Requirements

Python ≥ 3.9
Running Meilisearch instance
Node.js (for testing with MCP Inspector)

Usage

Environment Variables

MEILI_HTTP_ADDR=http://localhost:7700  # Default Meilisearch URL
MEILI_MASTER_KEY=your_master_key       # Optional: Default Meilisearch API key

Dynamic Connection Configuration

The server provides tools to view and update connection settings at runtime:

get-connection-settings: View current connection URL and API key status
update-connection-settings: Update URL and/or API key to connect to a different Meilisearch instance

Example usage through MCP:

// Get current settings
{
  "name": "get-connection-settings"
}

// Update connection settings
{
  "name": "update-connection-settings",
  "arguments": {
    "url": "http://new-host:7700",
    "api_key": "new-api-key"
  }
}

Search Functionality

The server provides a flexible search tool that can search across one or all indices:

search: Search through Meilisearch indices with optional parameters

Example usage through MCP:

// Search in a specific index
{
  "name": "search",
  "arguments": {
    "query": "search term",
    "indexUid": "movies",
    "limit": 10
  }
}

// Search across all indices
{
  "name": "search",
  "arguments": {
    "query": "search term",
    "limit": 5,
    "sort": ["releaseDate:desc"]
  }
}

Available search parameters: - query: The search query (required) - indexUid: Specific index to search in (optional) - limit: Maximum number of results per index (optional, default: 20) - offset: Number of results to skip (optional, default: 0) - filter: Filter expression (optional) - sort: Sorting rules (optional)

Running the Server

python -m src.meilisearch_mcp

Usage with Claude Desktop

To use this with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "meilisearch": {
      "command": "uvx",
      "args": ["-n", "meilisearch-mcp"]
    }
  }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

Available Tools

Connection Management

get-connection-settings: View current Meilisearch connection URL and API key status
update-connection-settings: Update URL and/or API key to connect to a different instance

Index Management

create-index: Create a new index with optional primary key
list-indexes: List all available indexes
get-index-metrics: Get detailed metrics for a specific index

Document Operations

get-documents: Retrieve documents from an index with pagination
add-documents: Add or update documents in an index

Search

search: Flexible search across single or multiple indices with filtering and sorting options

Settings Management

get-settings: View current settings for an index
update-settings: Update index settings (ranking, faceting, etc.)

API Key Management

get-keys: List all API keys
create-key: Create new API key with specific permissions
delete-key: Delete an existing API key

Task Management

get-task: Get information about a specific task
get-tasks: List tasks with optional filters:
limit: Maximum number of tasks to return
from: Number of tasks to skip
reverse: Sort order of tasks
batchUids: Filter by batch UIDs
uids: Filter by task UIDs
canceledBy: Filter by cancellation source
types: Filter by task types
statuses: Filter by task statuses
indexUids: Filter by index UIDs
afterEnqueuedAt/beforeEnqueuedAt: Filter by enqueue time
afterStartedAt/beforeStartedAt: Filter by start time
afterFinishedAt/beforeFinishedAt: Filter by finish time
cancel-tasks: Cancel pending or enqueued tasks
delete-tasks: Delete completed tasks

System Monitoring

health-check: Basic health check
get-health-status: Comprehensive health status
get-version: Get Meilisearch version information
get-stats: Get database statistics
get-system-info: Get system-level information

Contributing

Fork repository
Create feature branch
Commit changes
Create pull request

License

MIT

[
  {
    "description": "Get current Meilisearch connection settings",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "get-connection-settings"
  },
  {
    "description": "Update Meilisearch connection settings",
    "inputSchema": {
      "properties": {
        "api_key": {
          "optional": true,
          "type": "string"
        },
        "url": {
          "optional": true,
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "update-connection-settings"
  },
  {
    "description": "Check Meilisearch server health",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "health-check"
  },
  {
    "description": "Get Meilisearch version information",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "get-version"
  },
  {
    "description": "Get database statistics",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "get-stats"
  },
  {
    "description": "Create a new Meilisearch index",
    "inputSchema": {
      "properties": {
        "primaryKey": {
          "optional": true,
          "type": "string"
        },
        "uid": {
          "type": "string"
        }
      },
      "required": [
        "uid"
      ],
      "type": "object"
    },
    "name": "create-index"
  },
  {
    "description": "List all Meilisearch indexes",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "list-indexes"
  },
  {
    "description": "Get documents from an index",
    "inputSchema": {
      "properties": {
        "indexUid": {
          "type": "string"
        },
        "limit": {
          "optional": true,
          "type": "integer"
        },
        "offset": {
          "optional": true,
          "type": "integer"
        }
      },
      "required": [
        "indexUid"
      ],
      "type": "object"
    },
    "name": "get-documents"
  },
  {
    "description": "Add documents to an index",
    "inputSchema": {
      "properties": {
        "documents": {
          "type": "array"
        },
        "indexUid": {
          "type": "string"
        },
        "primaryKey": {
          "optional": true,
          "type": "string"
        }
      },
      "required": [
        "indexUid",
        "documents"
      ],
      "type": "object"
    },
    "name": "add-documents"
  },
  {
    "description": "Get current settings for an index",
    "inputSchema": {
      "properties": {
        "indexUid": {
          "type": "string"
        }
      },
      "required": [
        "indexUid"
      ],
      "type": "object"
    },
    "name": "get-settings"
  },
  {
    "description": "Update settings for an index",
    "inputSchema": {
      "properties": {
        "indexUid": {
          "type": "string"
        },
        "settings": {
          "type": "object"
        }
      },
      "required": [
        "indexUid",
        "settings"
      ],
      "type": "object"
    },
    "name": "update-settings"
  },
  {
    "description": "Search through Meilisearch indices. If indexUid is not provided, it will search across all indices.",
    "inputSchema": {
      "properties": {
        "filter": {
          "optional": true,
          "type": "string"
        },
        "indexUid": {
          "optional": true,
          "type": "string"
        },
        "limit": {
          "optional": true,
          "type": "integer"
        },
        "offset": {
          "optional": true,
          "type": "integer"
        },
        "query": {
          "type": "string"
        },
        "sort": {
          "items": {
            "type": "string"
          },
          "optional": true,
          "type": "array"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "name": "search"
  },
  {
    "description": "Get information about a specific task",
    "inputSchema": {
      "properties": {
        "taskUid": {
          "type": "integer"
        }
      },
      "required": [
        "taskUid"
      ],
      "type": "object"
    },
    "name": "get-task"
  },
  {
    "description": "Get list of tasks with optional filters",
    "inputSchema": {
      "properties": {
        "afterEnqueuedAt": {
          "optional": true,
          "type": "string"
        },
        "afterFinishedAt": {
          "optional": true,
          "type": "string"
        },
        "afterStartedAt": {
          "optional": true,
          "type": "string"
        },
        "batchUids": {
          "items": {
            "type": "string"
          },
          "optional": true,
          "type": "array"
        },
        "beforeEnqueuedAt": {
          "optional": true,
          "type": "string"
        },
        "beforeFinishedAt": {
          "optional": true,
          "type": "string"
        },
        "beforeStartedAt": {
          "optional": true,
          "type": "string"
        },
        "canceledBy": {
          "items": {
            "type": "string"
          },
          "optional": true,
          "type": "array"
        },
        "from": {
          "optional": true,
          "type": "integer"
        },
        "indexUids": {
          "items": {
            "type": "string"
          },
          "optional": true,
          "type": "array"
        },
        "limit": {
          "optional": true,
          "type": "integer"
        },
        "reverse": {
          "optional": true,
          "type": "boolean"
        },
        "statuses": {
          "items": {
            "type": "string"
          },
          "optional": true,
          "type": "array"
        },
        "types": {
          "items": {
            "type": "string"
          },
          "optional": true,
          "type": "array"
        },
        "uids": {
          "items": {
            "type": "integer"
          },
          "optional": true,
          "type": "array"
        }
      },
      "type": "object"
    },
    "name": "get-tasks"
  },
  {
    "description": "Cancel tasks based on filters",
    "inputSchema": {
      "properties": {
        "indexUids": {
          "optional": true,
          "type": "string"
        },
        "statuses": {
          "optional": true,
          "type": "string"
        },
        "types": {
          "optional": true,
          "type": "string"
        },
        "uids": {
          "optional": true,
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "cancel-tasks"
  },
  {
    "description": "Get list of API keys",
    "inputSchema": {
      "properties": {
        "limit": {
          "optional": true,
          "type": "integer"
        },
        "offset": {
          "optional": true,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "name": "get-keys"
  },
  {
    "description": "Create a new API key",
    "inputSchema": {
      "properties": {
        "actions": {
          "type": "array"
        },
        "description": {
          "optional": true,
          "type": "string"
        },
        "expiresAt": {
          "optional": true,
          "type": "string"
        },
        "indexes": {
          "type": "array"
        }
      },
      "required": [
        "actions",
        "indexes"
      ],
      "type": "object"
    },
    "name": "create-key"
  },
  {
    "description": "Delete an API key",
    "inputSchema": {
      "properties": {
        "key": {
          "type": "string"
        }
      },
      "required": [
        "key"
      ],
      "type": "object"
    },
    "name": "delete-key"
  },
  {
    "description": "Get comprehensive health status of Meilisearch",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "get-health-status"
  },
  {
    "description": "Get detailed metrics for an index",
    "inputSchema": {
      "properties": {
        "indexUid": {
          "type": "string"
        }
      },
      "required": [
        "indexUid"
      ],
      "type": "object"
    },
    "name": "get-index-metrics"
  },
  {
    "description": "Get system-level information",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "get-system-info"
  }
]