Skip to content
Back to search

meilisearch-mcp

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/meilisearch--meilisearch-mcp/badge.svg)](/listings/meilisearch--meilisearch-mcp)

HTML

<a href="/listings/meilisearch--meilisearch-mcp"><img src="/api/listings/meilisearch--meilisearch-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Get up and running in just 3 steps!

1️⃣ Install the package

# Using pip
pip install meilisearch-mcp

# Or using uvx (recommended)
uvx -n meilisearch-mcp

2️⃣ Configure Claude Desktop

Add this to your `claude_desktop_config.json`:

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

3️⃣ Start Meilisearch

# Using Docker (recommended)
docker run -d -p 7700:7700 getmeili/meilisearch:v1.28

# Or using Homebrew
brew install meilisearch
meilisearch

That's it! Now you can ask your AI assistant to search and manage your Meilisearch data! 🎉

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 584 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="https://github.com/meilisearch/meilisearch/blob/main/assets/logo.svg" alt="Meilisearch" width="200" height="200" />
  3. </div>
  4. <h1 align="center">Meilisearch MCP Server</h1>
  5. <h4 align="center">
  6. <a href="https://github.com/meilisearch/meilisearch">Meilisearch</a> |
  7. <a href="https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-mcp">Meilisearch Cloud</a> |
  8. <a href="https://www.meilisearch.com/docs">Documentation</a> |
  9. <a href="https://discord.meilisearch.com">Discord</a>
  10. </h4>
  11. <p align="center">
  12. <a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/v/meilisearch-mcp.svg" alt="PyPI version"></a>
  13. <a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/pyversions/meilisearch-mcp.svg" alt="Python Versions"></a>
  14. <a href="https://github.com/meilisearch/meilisearch-mcp/actions"><img src="https://github.com/meilisearch/meilisearch-mcp/workflows/Test%20and%20Lint/badge.svg" alt="Tests"></a>
  15. <a href="https://github.com/meilisearch/meilisearch-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="License"></a>
  16. <a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/dm/meilisearch-mcp" alt="Downloads"></a>
  17. </p>
  18. > [!WARNING]
  19. > **This package is deprecated. Use the native Meilisearch MCP server instead.**
  20. >
  21. > Meilisearch now ships a built-in MCP server (Meilisearch v1.54 and later). It is exposed on the `/mcp` route of your instance over HTTP, so you do not need to install or run this Python package anymore.
  22. >
  23. > 👉 Follow the [Meilisearch MCP guide](https://www.meilisearch.com/docs/getting_started/integrations/mcp) to set it up.
  24. >
  25. > This repository is a local stdio wrapper built before native support existed. It is no longer actively maintained and is kept only for existing users.
  26. <p align="center">⚡ Connect any LLM to Meilisearch and supercharge your AI with lightning-fast search capabilities! 🔍</p>
  27. ## 🤔 What is this?
  28. The Meilisearch MCP Server is a Model Context Protocol server that enables any MCP-compatible client (including Claude, OpenAI agents, and other LLMs) to interact with Meilisearch. This stdio-based server allows AI assistants to manage search indices, perform searches, and handle your data through natural conversation.
  29. **Why use this?**
  30. - 🤖 **Universal Compatibility** - Works with any MCP client, not just Claude
  31. - 🗣️ **Natural Language Control** - Manage Meilisearch through conversation with any LLM
  32. - 🚀 **Zero Learning Curve** - No need to learn Meilisearch's API
  33. - 🔧 **Full Feature Access** - All Meilisearch capabilities at your fingertips
  34. - 🔄 **Dynamic Connections** - Switch between Meilisearch instances on the fly
  35. - 📡 **stdio Transport** - Uses stdio only; for HTTP, use the [native Meilisearch MCP server](https://www.meilisearch.com/docs/getting_started/integrations/mcp)
  36. ## ✨ Key Features
  37. - 📊 **Index & Document Management** - Create, update, and manage search indices
  38. - 🔍 **Smart Search** - Search across single or multiple indices with advanced filtering
  39. - ⚙️ **Settings Configuration** - Fine-tune search relevancy and performance
  40. - 📈 **Task Monitoring** - Track indexing progress and system operations
  41. - 🔐 **API Key Management** - Secure access control
  42. - 🏥 **Health Monitoring** - Keep tabs on your Meilisearch instance
  43. - 🧱 **Structured Tool Output** - Every data-returning tool provides `structuredContent` alongside text, per the latest MCP specification
  44. - 🔀 **Modern MCP Stack** - Built on the official MCP Python SDK v2 (spec 2026-07-28), backwards compatible with older MCP clients
  45. - 🐍 **Python Implementation** - [TypeScript version also available](https://github.com/devlimelabs/meilisearch-ts-mcp)
  46. ## 🚀 Quick Start
  47. Get up and running in just 3 steps!
  48. ### 1️⃣ Install the package
  49. ```bash
  50. # Using pip
  51. pip install meilisearch-mcp
  52. # Or using uvx (recommended)
  53. uvx -n meilisearch-mcp
  54. ```
  55. ### 2️⃣ Configure Claude Desktop
  56. Add this to your `claude_desktop_config.json`:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "meilisearch": {
  61. "command": "uvx",
  62. "args": ["-n", "meilisearch-mcp"]
  63. }
  64. }
  65. }
  66. ```
  67. ### 3️⃣ Start Meilisearch
  68. ```bash
  69. # Using Docker (recommended)
  70. docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
  71. # Or using Homebrew
  72. brew install meilisearch
  73. meilisearch
  74. ```
  75. That's it! Now you can ask your AI assistant to search and manage your Meilisearch data! 🎉
  76. ## 📚 Examples
  77. ### 💬 Talk to your AI assistant naturally:
  78. ```
  79. You: "Create a new index called 'products' with 'id' as the primary key"
  80. AI: I'll create that index for you... ✓ Index 'products' created successfully!
  81. You: "Add some products to the index"
  82. AI: I'll add those products... ✓ Added 5 documents to 'products' index
  83. You: "Search for products under $50 with 'electronics' in the category"
  84. AI: I'll search for those products... Found 12 matching products!
  85. ```
  86. ### 🔍 Advanced Search Example:
  87. ```
  88. You: "Search across all my indices for 'machine learning' and sort by date"
  89. AI: Searching across all indices... Found 47 results from 3 indices:
  90. - 'blog_posts': 23 articles about ML
  91. - 'documentation': 15 technical guides
  92. - 'tutorials': 9 hands-on tutorials
  93. ```
  94. ## 🔧 Installation
  95. ### Prerequisites
  96. - Python ≥ 3.10
  97. - Running Meilisearch instance
  98. - MCP-compatible client (Claude Desktop, OpenAI agents, etc.)
  99. ### From PyPI
  100. ```bash
  101. pip install meilisearch-mcp
  102. ```
  103. ### From Source (for development)
  104. ```bash
  105. # Clone repository
  106. git clone https://github.com/meilisearch/meilisearch-mcp.git
  107. cd meilisearch-mcp
  108. # Create virtual environment and install
  109. uv venv
  110. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  111. uv pip install -e .
  112. ```
  113. ### Using Docker
  114. Perfect for containerized environments like n8n workflows!
  115. #### From Docker Hub
  116. ```bash
  117. # Pull the latest image
  118. docker pull getmeili/meilisearch-mcp:latest
  119. # Or a specific version
  120. docker pull getmeili/meilisearch-mcp:0.5.0
  121. # Run the container
  122. docker run -it \
  123. -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  124. -e MEILI_MASTER_KEY=your-master-key \
  125. getmeili/meilisearch-mcp:latest
  126. ```
  127. #### Build from Source
  128. ```bash
  129. # Build your own image
  130. docker build -t meilisearch-mcp .
  131. docker run -it \
  132. -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  133. -e MEILI_MASTER_KEY=your-master-key \
  134. meilisearch-mcp
  135. ```
  136. #### Integration with n8n
  137. For n8n workflows, you can use the Docker image directly in your setup:
  138. ```yaml
  139. meilisearch-mcp:
  140. image: getmeili/meilisearch-mcp:latest
  141. environment:
  142. - MEILI_HTTP_ADDR=http://meilisearch:7700
  143. - MEILI_MASTER_KEY=masterKey
  144. ```
  145. ## 🛠️ What Can You Do?
  146. <details>
  147. <summary><b>🔗 Connection Management</b></summary>
  148. - View current connection settings
  149. - Switch between Meilisearch instances dynamically
  150. - Update API keys on the fly
  151. </details>
  152. <details>
  153. <summary><b>📁 Index Operations</b></summary>
  154. - Create new indices with custom primary keys
  155. - List all indices with stats
  156. - Delete indices and their data
  157. - Get detailed index metrics
  158. </details>
  159. <details>
  160. <summary><b>📄 Document Management</b></summary>
  161. - Add or update documents
  162. - Retrieve documents with pagination
  163. - Bulk import data
  164. </details>
  165. <details>
  166. <summary><b>🔍 Search Capabilities</b></summary>
  167. - Search with filters, sorting, and facets
  168. - Multi-index search
  169. - Semantic search with vectors
  170. - Hybrid search (keyword + semantic)
  171. </details>
  172. <details>
  173. <summary><b>⚙️ Settings & Configuration</b></summary>
  174. - Configure ranking rules
  175. - Set up faceting and filtering
  176. - Manage searchable attributes
  177. - Customize typo tolerance
  178. </details>
  179. <details>
  180. <summary><b>🔐 Security</b></summary>
  181. - Create and manage API keys
  182. - Set granular permissions
  183. - Monitor key usage
  184. ⚠️ Note: While you can add and update hosts and API keys directly in chat for convenience, this approach is primarily designed for development use cases (like connecting to multiple instances on the fly). It does not follow best MCP security practices and should not be used in production environments without proper safeguards.
  185. </details>
  186. <details>
  187. <summary><b>📊 Monitoring & Health</b></summary>
  188. - Health checks
  189. - System statistics
  190. - Task monitoring
  191. - Version information
  192. </details>
  193. ## 🌍 Environment Variables
  194. Configure default connection settings:
  195. ```bash
  196. MEILI_HTTP_ADDR=http://localhost:7700 # Default Meilisearch URL
  197. MEILI_MASTER_KEY=your_master_key # Optional: Default API key
  198. ```
  199. ## 💻 Development
  200. ### Setting Up Development Environment
  201. 1. **Start Meilisearch**:
  202. ```bash
  203. docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
  204. ```
  205. 2. **Install Development Dependencies**:
  206. ```bash
  207. uv pip install -r requirements-dev.txt
  208. ```
  209. 3. **Run Tests**:
  210. ```bash
  211. python -m pytest tests/ -v
  212. ```
  213. 4. **Format Code**:
  214. ```bash
  215. black src/ tests/
  216. ```
  217. ### Testing with MCP Inspector
  218. ```bash
  219. npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp
  220. ```
  221. ## 🤝 Community & Support
  222. We'd love to hear from you! Here's how to get help and connect:
  223. - 💬 [Join our Discord](https://discord.meilisearch.com) - Chat with the community
  224. - 🐛 [Report Issues](https://github.com/meilisearch/meilisearch-mcp/issues) - Found a bug? Let us know!
  225. - 💡 [Feature Requests](https://github.com/meilisearch/meilisearch-mcp/issues) - Have an idea? We're listening!
  226. - 📖 [Meilisearch Docs](https://www.meilisearch.com/docs) - Learn more about Meilisearch
  227. ## 🤗 Contributing
  228. We welcome contributions! Here's how to get started:
  229. 1. Fork the repository
  230. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  231. 3. Write tests for your changes
  232. 4. Make your changes and run tests
  233. 5. Format your code with `black`
  234. 6. Commit your changes (`git commit -m 'Add amazing feature'`)
  235. 7. Push to your branch (`git push origin feature/amazing-feature`)
  236. 8. Open a Pull Request
  237. See our [Contributing Guidelines](#contributing-1) for more details.
  238. ## 📦 Release Process
  239. This project uses automated versioning and publishing. When the version in `pyproject.toml` changes on the `main` branch, the package is automatically published to PyPI.
  240. See the [Release Process](#release-process-1) section for detailed instructions.
  241. ## 📄 License
  242. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  243. ---
  244. <p align="center">
  245. <b>Meilisearch</b> is an open-source search engine that offers a delightful search experience.<br>
  246. Learn more about Meilisearch at <a href="https://www.meilisearch.com">meilisearch.com</a>
  247. </p>
  248. ---
  249. <details>
  250. <summary><h2>📖 Full Documentation</h2></summary>
  251. ### Available Tools
  252. #### Connection Management
  253. - `get-connection-settings`: View current Meilisearch connection URL and API key status
  254. - `update-connection-settings`: Update URL and/or API key to connect to a different instance
  255. #### Index Management
  256. - `create-index`: Create a new index with optional primary key
  257. - `list-indexes`: List all available indexes
  258. - `delete-index`: Delete an existing index and all its documents
  259. - `get-index-metrics`: Get detailed metrics for a specific index
  260. #### Document Operations
  261. - `get-documents`: Retrieve documents from an index with pagination
  262. - `add-documents`: Add or update documents in an index
  263. #### Search
  264. - `search`: Flexible search across single or multiple indices with filtering and sorting options
  265. #### Settings Management
  266. - `get-settings`: View current settings for an index
  267. - `update-settings`: Update index settings (ranking, faceting, etc.)
  268. #### API Key Management
  269. - `get-keys`: List all API keys
  270. - `create-key`: Create new API key with specific permissions
  271. - `delete-key`: Delete an existing API key
  272. #### Task Management
  273. - `get-task`: Get information about a specific task
  274. - `get-tasks`: List tasks with optional filters
  275. - `cancel-tasks`: Cancel pending or enqueued tasks
  276. #### System Monitoring
  277. - `health-check`: Basic health check
  278. - `get-health-status`: Comprehensive health status
  279. - `get-version`: Get Meilisearch version information
  280. - `get-stats`: Get database statistics
  281. - `get-system-info`: Get system-level information
  282. ### Development Setup
  283. #### Prerequisites
  284. 1. **Start Meilisearch server**:
  285. ```bash
  286. # Using Docker (recommended for development)
  287. docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
  288. # Or using brew (macOS)
  289. brew install meilisearch
  290. meilisearch
  291. # Or download from https://github.com/meilisearch/meilisearch/releases
  292. ```
  293. 2. **Install development tools**:
  294. ```bash
  295. # Install uv for Python package management
  296. pip install uv
  297. # Install Node.js for MCP Inspector testing
  298. # Visit https://nodejs.org/ or use your package manager
  299. ```
  300. ### Running Tests
  301. This project includes comprehensive integration tests that verify MCP tool functionality:
  302. ```bash
  303. # Run all tests
  304. python -m pytest tests/ -v
  305. # Run specific test file
  306. python -m pytest tests/test_mcp_client.py -v
  307. # Run tests with coverage report
  308. python -m pytest --cov=src tests/
  309. # Run tests in watch mode (requires pytest-watch)
  310. pytest-watch tests/
  311. ```
  312. **Important**: Tests require a running Meilisearch instance on `http://localhost:7700`.
  313. ### Code Quality
  314. ```bash
  315. # Format code with Black
  316. black src/ tests/
  317. # Run type checking (if mypy is configured)
  318. mypy src/
  319. # Lint code (if flake8 is configured)
  320. flake8 src/ tests/
  321. ```
  322. ### Contributing Guidelines
  323. 1. **Fork and clone** the repository
  324. 2. **Set up development environment** following the Development Setup section above
  325. 3. **Create a feature branch** from `main`
  326. 4. **Write tests first** if adding new functionality (Test-Driven Development)
  327. 5. **Run tests locally** to ensure all tests pass before committing
  328. 6. **Format code** with Black and ensure code quality
  329. 7. **Commit changes** with descriptive commit messages
  330. 8. **Push to your fork** and create a pull request
  331. ### Development Workflow
  332. ```bash
  333. # Create feature branch
  334. git checkout -b feature/your-feature-name
  335. # Make your changes, write tests first
  336. # Edit files...
  337. # Run tests to ensure everything works
  338. python -m pytest tests/ -v
  339. # Format code
  340. black src/ tests/
  341. # Commit and push
  342. git add .
  343. git commit -m "Add feature description"
  344. git push origin feature/your-feature-name
  345. ```
  346. ### Testing Guidelines
  347. - All new features should include tests
  348. - Tests should pass before submitting PRs
  349. - Use descriptive test names and clear assertions
  350. - Test both success and error cases
  351. - Ensure Meilisearch is running before running tests
  352. ### Release Process
  353. This project uses automated versioning and publishing to PyPI. The release process is designed to be simple and automated.
  354. #### How Releases Work
  355. 1. **Automated Publishing**: When the version number in `pyproject.toml` changes on the `main` branch, a GitHub Action automatically:
  356. - Builds the Python package
  357. - Publishes it to PyPI using trusted publishing
  358. - Creates a new release on GitHub
  359. 2. **Version Detection**: The workflow compares the current version in `pyproject.toml` with the previous commit to detect changes
  360. 3. **PyPI Publishing**: Uses PyPA's official publish action with trusted publishing (no manual API keys needed)
  361. #### Creating a New Release
  362. To create a new release, follow these steps:
  363. ##### 1. Determine Version Number
  364. Follow [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH):
  365. - **PATCH** (e.g., 0.4.0 → 0.4.1): Bug fixes, documentation updates, minor improvements
  366. - **MINOR** (e.g., 0.4.0 → 0.5.0): New features, new MCP tools, significant enhancements
  367. - **MAJOR** (e.g., 0.5.0 → 1.0.0): Breaking changes, major API changes
  368. ##### 2. Update Version and Create PR
  369. ```bash
  370. # 1. Create a branch from latest main
  371. git checkout main
  372. git pull origin main
  373. git checkout -b release/v0.5.0
  374. # 2. Update version in pyproject.toml
  375. # Edit the version = "0.4.0" line to your new version
  376. # 3. Commit and push
  377. git add pyproject.toml
  378. git commit -m "Bump version to 0.5.0"
  379. git push origin release/v0.5.0
  380. # 4. Create PR and get it reviewed/merged
  381. gh pr create --title "Release v0.5.0" --body "Bump version for release"
  382. ```
  383. ##### 3. Merge to Main
  384. Once the PR is approved and merged to `main`, the GitHub Action will automatically:
  385. 1. Detect the version change
  386. 2. Build the package
  387. 3. Publish to PyPI at https://pypi.org/p/meilisearch-mcp
  388. 4. Make the new version available via `pip install meilisearch-mcp`
  389. ##### 4. Verify Release
  390. After merging, verify the release:
  391. ```bash
  392. # Check GitHub Action status
  393. gh run list --workflow=publish.yml
  394. # Verify on PyPI (may take a few minutes)
  395. pip index versions meilisearch-mcp
  396. # Test installation of new version
  397. pip install --upgrade meilisearch-mcp
  398. ```
  399. ### Release Workflow File
  400. The automated release is handled by `.github/workflows/publish.yml`, which:
  401. - Triggers on pushes to `main` branch
  402. - Checks if `pyproject.toml` version changed
  403. - Uses Python 3.10 and official build tools
  404. - Publishes using trusted publishing (no API keys required)
  405. - Provides verbose output for debugging
  406. ### Troubleshooting Releases
  407. **Release didn't trigger**: Check that the version in `pyproject.toml` actually changed between commits
  408. **Build failed**: Check the GitHub Actions logs for Python package build errors
  409. **PyPI publish failed**: Verify the package name and that trusted publishing is configured properly
  410. **Version conflicts**: Ensure the new version number hasn't been used before on PyPI
  411. ### Development vs Production Versions
  412. - **Development**: Install from source using `pip install -e .`
  413. - **Production**: Install from PyPI using `pip install meilisearch-mcp`
  414. - **Specific version**: Install using `pip install meilisearch-mcp==0.5.0`
  415. </details>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.