GitHub - meilisearch/meilisearch-mcp: A Model Context Protocol (MCP) server for interacting with Meilisearch through LLM interfaces. (original) (raw)

Meilisearch MCP Server

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

Meilisearch Server MCP server

Features

Installation

Clone repository

git clone cd meilisearch-mcp

Create virtual environment and install

uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e .

Install development dependencies (for testing and development)

uv pip install -r requirements-dev.txt

Requirements

Development Setup

Prerequisites

  1. Start Meilisearch server:

Using Docker (recommended for development)

docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

Or using brew (macOS)

brew install meilisearch
meilisearch

Or download from https://github.com/meilisearch/meilisearch/releases

  1. Install development tools:

Install uv for Python package management

pip install uv

Install Node.js for MCP Inspector testing

Visit https://nodejs.org/ or use your package manager

Running Tests

This project includes comprehensive integration tests that verify MCP tool functionality:

Run all tests

python -m pytest tests/ -v

Run specific test file

python -m pytest tests/test_mcp_client.py -v

Run tests with coverage report

python -m pytest --cov=src tests/

Run tests in watch mode (requires pytest-watch)

pytest-watch tests/

Important: Tests require a running Meilisearch instance on http://localhost:7700. The tests will:

Code Quality

Format code with Black

black src/ tests/

Run type checking (if mypy is configured)

mypy src/

Lint code (if flake8 is configured)

flake8 src/ tests/

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:

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:

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:

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

Index Management

Document Operations

Settings Management

API Key Management

Task Management

System Monitoring

Contributing

We welcome contributions! Please follow these guidelines:

  1. Fork and clone the repository
  2. Set up development environment following the Development Setup section above
  3. Create a feature branch from main
  4. Write tests first if adding new functionality (Test-Driven Development)
  5. Run tests locally to ensure all tests pass before committing
  6. Format code with Black and ensure code quality
  7. Commit changes with descriptive commit messages
  8. Push to your fork and create a pull request

Development Workflow

Create feature branch

git checkout -b feature/your-feature-name

Make your changes, write tests first

Edit files...

Run tests to ensure everything works

python -m pytest tests/ -v

Format code

black src/ tests/

Commit and push

git add . git commit -m "Add feature description" git push origin feature/your-feature-name

Testing Guidelines

Release Process

This project uses automated versioning and publishing to PyPI. The release process is designed to be simple and automated.

How Releases Work

  1. Automated Publishing: When the version number in pyproject.toml changes on the main branch, a GitHub Action automatically:
    • Builds the Python package
    • Publishes it to PyPI using trusted publishing
    • Creates a new release on GitHub
  2. Version Detection: The workflow compares the current version in pyproject.toml with the previous commit to detect changes
  3. PyPI Publishing: Uses PyPA's official publish action with trusted publishing (no manual API keys needed)

Creating a New Release

To create a new release, follow these steps:

1. Determine Version Number

Follow Semantic Versioning (MAJOR.MINOR.PATCH):

2. Update Version and Create PR

1. Create a branch from latest main

git checkout main git pull origin main git checkout -b release/v0.5.0

2. Update version in pyproject.toml

Edit the version = "0.4.0" line to your new version

3. Commit and push

git add pyproject.toml git commit -m "Bump version to 0.5.0" git push origin release/v0.5.0

4. Create PR and get it reviewed/merged

gh pr create --title "Release v0.5.0" --body "Bump version for release"

3. Merge to Main

Once the PR is approved and merged to main, the GitHub Action will automatically:

  1. Detect the version change
  2. Build the package
  3. Publish to PyPI at https://pypi.org/p/meilisearch-mcp
  4. Make the new version available via pip install meilisearch-mcp

4. Verify Release

After merging, verify the release:

Check GitHub Action status

gh run list --workflow=publish.yml

Verify on PyPI (may take a few minutes)

pip index versions meilisearch-mcp

Test installation of new version

pip install --upgrade meilisearch-mcp

Release Workflow File

The automated release is handled by .github/workflows/publish.yml, which:

Troubleshooting Releases

Release didn't trigger: Check that the version in pyproject.toml actually changed between commits

Build failed: Check the GitHub Actions logs for Python package build errors

PyPI publish failed: Verify the package name and that trusted publishing is configured properly

Version conflicts: Ensure the new version number hasn't been used before on PyPI

Development vs Production Versions

License

MIT