Meilisearch MCP Server Cursor IDE Setup 2026: uvx Install, MEILI_HTTP_ADDR & Master Key

How do you connect Meilisearch to Cursor? Install the official server with uvx -n meilisearch-mcp (Python 3.10+, via uv rather than npm), add a meilisearch entry to ~/.cursor/mcp.json that runs it, and point it at a running Meilisearch instance with the MEILI_HTTP_ADDR and MEILI_MASTER_KEY environment variables. From there Cursor can create indexes, add documents, run searches, and adjust settings — all against a real Meilisearch deployment, not a bundled one.

That last part matters: this MCP server is a client, not a database. It doesn't ship Meilisearch itself. If you don't already have an instance running somewhere — locally via Docker, or a hosted Meilisearch Cloud project — connecting the MCP server has nothing to talk to.

What the Meilisearch MCP Server Can Do

The tool set maps closely to Meilisearch's own REST API, grouped into seven areas:

Because index and settings changes in Meilisearch are asynchronous, most write operations here return a task ID rather than an immediate result — worth knowing before you assume a "create index" prompt failed just because Cursor doesn't immediately confirm it.

Prerequisites

Step 1: Confirm Meilisearch Is Actually Running

Before touching Cursor, hit the instance directly:

curl http://localhost:7700/health

A {"status":"available"} response means you're good. If this fails, fix the Meilisearch instance itself first — no MCP config will get an agent talking to a database that isn't up.

Step 2: Add the MCP Entry to Cursor

Open ~/.cursor/mcp.json (or Cursor Settings → Tools & MCP → Add Custom MCP) and add:

{
  "mcpServers": {
    "meilisearch": {
      "command": "uvx",
      "args": ["-n", "meilisearch-mcp"],
      "env": {
        "MEILI_HTTP_ADDR": "http://localhost:7700",
        "MEILI_MASTER_KEY": "your-master-key"
      }
    }
  }
}

MEILI_HTTP_ADDR defaults to http://localhost:7700 if you omit it, but set it explicitly anyway — it's the one setting you'll actually need to change the moment you point this at a staging instance or Meilisearch Cloud project instead of local Docker. MEILI_MASTER_KEY is optional for an unauthenticated local instance; leave it out of the env block entirely rather than setting it to an empty string, which some clients treat as a literal (invalid) key.

Restart Cursor or reload its MCP panel after saving.

Alternative Install Methods

uvx is the maintainers' recommended path since it doesn't require a separate install step, but two alternatives exist:

pip, if you'd rather manage it in an existing Python environment:

pip install meilisearch-mcp

Docker, if you want the MCP server itself containerized rather than running via uv on the host:

docker pull getmeili/meilisearch-mcp:latest
docker run -it \
  -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  getmeili/meilisearch-mcp:latest

Note this is a different image than the one running Meilisearch itself (getmeili/meilisearch) — don't confuse the database image with the MCP wrapper image; they have similar names and different jobs.

Verify the Connection

Ask something that requires the agent to actually call the running instance:

Check the health and version of my Meilisearch instance, then list
the indexes that currently exist

A real version string and index list (even an empty one) confirms the connection works end to end. If Cursor reports no tools available, the uvx process likely failed to start — check that uvx --version runs cleanly in a terminal before assuming the mcp.json entry is wrong.

Practical Workflows

Standing up a new index mid-conversation

Create a Meilisearch index called "support_articles" with "title"
and "body" as searchable attributes, then add these three
documents: [paste JSON]

Debugging why a search returns unexpected results

Search the "products" index for "wireless mouse" and show me the
current ranking rules and searchable attributes for that index —
I want to know why a clearly relevant result isn't showing first

Checking instance health before a deploy

Get the current task queue status and instance stats for my
Meilisearch instance — I want to confirm nothing's backed up
before we point production traffic at it

The Part Worth Slowing Down For

Meilisearch's own maintainers are explicit that the MCP server's connection-update tools — the ones that let an agent change MEILI_HTTP_ADDR or reconfigure which instance it's talking to mid-session — are built for development use cases and don't carry production-grade security safeguards. That's a real caveat, not boilerplate: an agent with write access to Meilisearch's connection settings and API key management could, in principle, be steered by a bad prompt (yours or an injected one from search results the agent reads) into pointing itself at an instance you didn't intend, or minting a new API key. Scope what you connect this to accordingly — a local dev index is a reasonable target for broad agent access; a production Meilisearch Cloud project holding real customer data is not, at least not with a master key that has full write and key-management privileges.

If you need the agent to search a production index but nothing more, look at whether Meilisearch's API key scoping (search-only keys, restricted to specific indexes) covers your case, and use one of those instead of the master key in the env block.

Troubleshooting

uvx: command not found
uv isn't installed or isn't on your PATH. Reinstall with the curl script above and open a new terminal — a shell that was open before installing uv won't have picked up the PATH change.

Server starts but every tool call fails with a connection error
MEILI_HTTP_ADDR doesn't match where Meilisearch is actually listening. If you're running Meilisearch in Docker and the MCP server on the host (not in Docker), localhost:7700 is usually correct; if the MCP server is also containerized, localhost inside that container won't reach a Meilisearch instance running on the host — use host.docker.internal:7700 or the appropriate Docker network address instead.

"Unauthorized" errors on every request
Your Meilisearch instance has a master key set but MEILI_MASTER_KEY is missing or wrong in the env block. Double check the key against what's actually configured on the instance — a key copied from an old .env file after a key rotation is a common cause.

Tool call for "create index" returns immediately but the index doesn't show up yet
Index creation is asynchronous in Meilisearch. Check the returned task ID with the tasks tool, or just ask the agent to check again in a few seconds — this isn't a failure, it's normal async behavior.

Docker image confusion: pulled the wrong image
getmeili/meilisearch runs the database. getmeili/meilisearch-mcp runs the MCP wrapper that talks to a database. If tool calls fail immediately with nothing resembling a Meilisearch error, confirm you didn't run the database image and point Cursor at it expecting MCP behavior.

Frequently Asked Questions

Q: Does the Meilisearch MCP server include Meilisearch itself?
A: No. It's a client that connects to a Meilisearch instance you already have running, whether local (Docker), self-hosted, or Meilisearch Cloud. You need a working instance before the MCP server has anything to talk to.

Q: Why uvx instead of npx like most other MCP servers?
A: The official Meilisearch MCP server is a Python package distributed for uv, not published to npm. npx won't find it under any package name — install uv and use uvx -n meilisearch-mcp instead.

Q: Is a master key required to use the Meilisearch MCP server?
A: Only if your Meilisearch instance has one set. Local dev instances often run without auth, in which case you can omit MEILI_MASTER_KEY from the env block entirely. Production and Meilisearch Cloud instances require it.

Q: Is it safe to point this at a production Meilisearch instance with a full master key?
A: Meilisearch's own maintainers note the connection-management tools aren't built with production-grade security safeguards. For production, prefer a scoped, search-only API key over the master key wherever the workflow allows it.

Q: What happens when I ask the agent to create an index or add documents?
A: Most write operations in Meilisearch are asynchronous and return a task ID rather than an immediate result. Use the task-status tool to confirm completion rather than assuming an operation failed if it doesn't show up instantly.

Related Guides

Official docs cited