<!-- Source: https://docs.marimo.io/guides/editor_features/mcp/ -->

# Model Context Protocol (MCP)

> **Experimental Feature**
>
> MCP features are currently experimental and under active development. Features and APIs may change.

marimo supports the Model Context Protocol (MCP) in two ways: as an [MCP server](https://docs.marimo.io/guides/editor_features/mcp/#mcp-server) that exposes marimo's [AI tools](https://docs.marimo.io/guides/editor_features/tools/) to external applications, and as an [MCP client](https://docs.marimo.io/guides/editor_features/mcp/#mcp-client) that connects [supported servers](https://docs.marimo.io/guides/editor_features/mcp/#supported-servers) to marimo's [chat panel](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel).

## Prerequisites

Both MCP server and client features require the MCP dependencies. Run marimo with MCP support using one of the following methods:

**uv:**

```bash
# run with uv in a project
uv run --with="marimo[mcp]" marimo edit notebook.py --mcp --no-token
```

**uvx:**

```bash
# run with uvx anywhere
uvx "marimo[mcp]" edit notebook.py --mcp --no-token
```

**pip:**

```bash
# install with pip and a venv
pip install "marimo[mcp]"
marimo edit notebook.py --mcp --no-token
```

> **Flags**
>
> The `--mcp` flag exposes an endpoint that provides access to your notebook data via the MCP server endpoint. Remove `--mcp` if you only want MCP Client features. The `--no-token` flag removes authentication, which should only be used for local development. Remove `--no-token` in production environments.

## MCP Server

marimo can expose its [AI tools](https://docs.marimo.io/guides/editor_features/tools/) through an MCP server endpoint, allowing external AI applications to interact with your notebooks. If your goal is to have a coding agent drive a live notebook, see [marimo pair](https://docs.marimo.io/guides/generate_with_ai/marimo_pair/) instead; the MCP server exposes lower-level, read-only tools.

[Video: https://docs.marimo.io/_static/docs-mcp-server.mp4](https://docs.marimo.io/_static/docs-mcp-server.mp4)

### Available tools

When connected to marimo's MCP server, external applications can access all [AI tools](https://docs.marimo.io/guides/editor_features/tools/).

### Available prompts

When connected to marimo's MCP server, external applications can access the following prompts:

| Prompt | Description |
| --- | --- |
| **active\_notebooks** | Get current active notebooks and their session IDs and file paths. Returns session IDs and file paths for all active marimo notebook sessions, along with guidance on using these IDs with marimo MCP tools. |
| **errors\_summary** | Get error summaries for all active notebooks. Returns a summary of all errors across active notebooks organized by notebook and cell, including error types, messages, and affected cell IDs. |

### Connecting external applications

marimo's MCP server works with any MCP-compatible application. Below are setup instructions for some commonly used applications:

> **Connection details**
>
> Replace `PORT` with your marimo server port in the examples below. If authentication is enabled, append `?access_token=YOUR_TOKEN` to the URL and replace `YOUR_TOKEN` with your marimo access token.

#### Claude Code

Use Claude Code's CLI to connect to marimo:

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

#### Cursor

Configure Cursor to connect to marimo's MCP server:

```json
{
  "mcpServers": {
    "marimo": {
      "url": "http://localhost:PORT/mcp/server"
    }
  }
}
```

#### VS Code

Create a .vscode/mcp.json file in your workspace and configure it to connect to marimo's MCP server:

```json
{
  "servers": {
    "marimo": {
      "type": "http",
      "url": "http://localhost:PORT/mcp/server"
    }
  }
}
```

### DNS rebinding protection

marimo's MCP server enables DNS rebinding protection by default, which validates the `Host` header on incoming requests. This is common when using proxies, gateways (e.g., ECS), CDNs (Cloudflare), or custom domains, where the forwarded `Host` header won't match the expected local host, causing `421 Misdirected Request` or `Invalid Host Header` errors. Pass `--mcp-allow-remote` to disable this check:

```bash
marimo edit notebook.py --mcp --mcp-allow-remote
```

## MCP Client

marimo can connect to external MCP servers to add additional tools and context to the [chat panel](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel).

### Supported servers

marimo currently supports the following MCP servers:

| Server | Description |
| --- | --- |
| `marimo` | Provides marimo's official documentation, API reference, and code examples |
| `context7` | Fetches up-to-date, version-specific documentation and code examples from official sources |

### Configuration

Enable MCP client servers through the marimo settings UI:

![](https://docs.marimo.io/_static/docs-mcp-client-settings.png)

*Enable MCP servers in the AI settings panel.*

Alternatively, configure MCP servers in your marimo configuration file:

marimo.toml
```toml
[mcp]
presets = ["marimo", "context7"]
```

Once configured, tools from these servers will be automatically available in the [chat panel when using ask mode](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel).

> **Custom MCP servers**
>
> Support for custom MCP server configuration is not yet available.

## Related documentation

- [AI tools](https://docs.marimo.io/guides/editor_features/tools/) - Available tools exposed by the MCP server
- [AI-assisted coding](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel) - Using the chat panel with MCP tools