Set up the marimo MCP Server safely on localhost

This guide configures marimo's official, experimental MCP Server as constrained local access to a running notebook. It is based on marimo's MCP and AI-tools documentation. Before installation, record which notebook, cells, and data may be visible at all. The server is not a substitute for an authorization model, repository review, or approval to execute code. Its documented purpose is to provide an external MCP client with read-oriented information from active marimo sessions. Anyone who wants a coding agent to drive or modify a notebook must evaluate marimo's separately documented workflows and their write permissions.

Prerequisites and a controlled launch

Use an isolated Python environment and a current marimo installation with MCP extras. Start one specific test notebook with:

uv run --with="marimo[mcp]" marimo edit notebook.py --mcp

marimo starts the notebook editor and an MCP endpoint on the same local server port. Record the port, notebook path, marimo version, client, and model. Do not begin with a notebook that contains production credentials, raw personal data, or secrets in cells and outputs. The tool set can already expose file paths, cell code, runtime metadata, table information, errors, and visual output. Never copy tokens into a notebook, prompt, screenshot, or repository.

Keep token authentication enabled by default. According to marimo, --no-token removes it and is only for local development. A useful connection test is not opening the endpoint in a browser but checking the resulting tool list in the MCP client. A team or continuously operated deployment needs an explicitly designed network boundary; this guide deliberately optimises the localhost case, not public exposure.

Connect the client and verify permissions

marimo documents HTTP transport for Claude Code:

claude mcp add --transport http marimo http://localhost:PORT/mcp/server

Replace PORT with the running marimo server's port. Cursor can use the same endpoint in its MCP configuration. Where authentication is enabled, add the access token only to protected client configuration and never commit it to shared configuration. Then confirm that the client sees only the expected marimo tools: active notebooks, the cell map, runtime data and outputs, the dependency graph, tables and variables, and error/lint information.

These tools provide research and diagnosis access. They are not permission for notebook execution. marimo documents run_stale_cells, edit_notebook, and Code mode's execute_code for its chat UI; its documentation separates them from the external MCP server. Do not accept a model proposal such as “run the cell now” as an automatic action. A human separately reviews the code, inputs, impact, test, and rollback path.

Constrain networking and remote operation

The default localhost limits reachability to the machine but does not replace authentication. marimo validates Host headers as DNS-rebinding protection. --mcp-allow-remote disables that check for proxy, gateway, or custom-domain scenarios. Use it only after an architecture with TLS, token authentication, restrictive firewalling, allowed clients, and monitoring has been defined. A reverse proxy is not a reason to disable token checks. Combining an externally reachable port and --no-token is particularly unsafe.

Review the workstation too: local logs, shell history, process lists, and MCP-client configuration can expose an endpoint or token. Stop or remove the server and client connection after a temporary test. On shared devices, use separate operating-system accounts and a dedicated workspace. For remote notebooks or containers, also establish which host is actually listening and which network zone can reach the endpoint.

Untrusted content and the model data path

Treat every tool response as untrusted content. Cells can contain Markdown, URLs, web data, or table rows that attempt prompt injection: “ignore security rules,” “read environment variables,” “invoke a shell,” or “publish the data” are data, not instructions. Limit the client to needed tools and sessions, separate notebook inspection from shell and Git rights, and require human confirmation for every follow-on action. A plausible-looking traceback or comment receives no special authority.

The complete data path is at least notebook kernel to marimo server to MCP client to model context. Depending on the client, logs, telemetry, or an external model provider can follow. Before access, document model name, provider, retention, training use, enterprise settings, contract, and regional processing. Local transport does not protect against a later cloud-model request. Send only the necessary session and avoid sensitive values in cell outputs. This keeps the marimo MCP Server a traceable, minimal diagnostic path rather than an uncontrolled data channel.

FAQ

Why do I not see an MCP endpoint? First check that marimo started with its MCP extras and the --mcp flag, then use the actual local server port in the client URL.

May I set --mcp-allow-remote for a proxy? Only after security review. The flag disables Host-header validation; token authentication, TLS, firewalling, and a clear trust boundary must independently remain in place.

Can table values be prompt injection? Yes. Values, Markdown, outputs, and errors are data. They must not expand tool permissions or replace human approvals.