# How to Set Up Open Notebook MCP Integration: Complete Configuration Guide

> Learn how to set up Open Notebook MCP integration by configuring the open-notebook-mcp server with uvx and setting environment variables in your client config.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-22

---

**Open Notebook MCP integration setup requires configuring the `open-notebook-mcp` server via `uvx` and setting two environment variables (`OPEN_NOTEBOOK_URL` and `OPEN_NOTEBOOK_PASSWORD`) in your client's JSON configuration file.**

The Model Context Protocol (MCP) is an open standard that enables AI applications like Claude Desktop and VS Code extensions to communicate directly with the Open Notebook API. According to the lfnovo/open-notebook source code, completing the MCP integration setup exposes notebooks, sources, notes, chat, and search capabilities to any MCP-compatible client, allowing AI assistants to interact with your research data as native tools.

## Installing the MCP Server

The MCP server is distributed as the `open-notebook-mcp` Python package. As documented in [`docs/5-CONFIGURATION/mcp-integration.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/mcp-integration.md) (lines 19-23), no manual installation is required because Claude Desktop and VS Code extensions automatically invoke the server via `uvx`.

When the client launches, it automatically runs `uvx open-notebook-mcp`, which spawns the MCP server and registers the Open Notebook endpoints.

## Configuring Claude Desktop

To enable MCP integration with Claude Desktop, you must edit the client's configuration JSON file. The file location depends on your operating system.

### macOS and Linux Configuration

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "open-notebook": {
      "command": "uvx",
      "args": ["open-notebook-mcp"],
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your_password_here"
      }
    }
  }
}

```

### Windows Configuration

Edit `%APPDATA%\Claude\claude_desktop_config.json` with the identical JSON structure shown above.

The configuration requires two environment variables:
- `OPEN_NOTEBOOK_URL`: Points to the FastAPI backend (default `http://localhost:5055`)
- `OPEN_NOTEBOOK_PASSWORD`: Required only if you enabled password protection in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)

## Configuring VS Code for MCP Integration

For VS Code MCP extensions, add a [`mcp.json`](https://github.com/lfnovo/open-notebook/blob/main/mcp.json) file under `.vscode/` or edit the global VS Code settings. As implemented in lfnovo/open-notebook (lines 66-78), the JSON payload follows this structure:

```json
{
  "servers": {
    "open-notebook": {
      "command": "uvx",
      "args": ["open-notebook-mcp"],
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your_password_here"
      }
    }
  }
}

```

## Remote Deployment Configuration

For remote Open Notebook deployments, replace `http://localhost:5055` with your reachable host. According to the documentation (lines 84-99), use the full URL including the path if applicable:

```json
{
  "env": {
    "OPEN_NOTEBOOK_URL": "https://notebook.yourdomain.com/api",
    "OPEN_NOTEBOOK_PASSWORD": "your_password_here"
  }
}

```

Ensure network and firewall rules allow inbound traffic on port 5055 for the FastAPI server defined in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).

## Available MCP Tools

Once the MCP integration setup is complete, the client can call any Open Notebook API endpoint via the MCP protocol. The supported tool set documented in [`docs/5-CONFIGURATION/mcp-integration.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/mcp-integration.md) (lines 115-165) includes:

- **Notebooks**: list, get, create, update, delete operations
- **Sources**: list, get, add, update, delete operations  
- **Notes**: list, get, create, update, delete operations
- **Chat**: create sessions, send messages, fetch history, list sessions
- **Search**: vector and text search with notebook filtering
- **Models**: list, get, create, update model configurations
- **Settings**: read and write application settings

## Troubleshooting Connection Issues

If you encounter errors after your MCP integration setup, verify the following as outlined in the documentation (lines 86-92):

1. `OPEN_NOTEBOOK_URL` points to a running FastAPI instance (default port 5055)
2. The password matches the value configured in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)
3. Network and firewall rules allow traffic on port 5055 for remote servers

Restart Claude Desktop or reload VS Code after saving configuration changes to apply the new settings.

## Summary

- Open Notebook MCP integration setup uses the `open-notebook-mcp` package invoked via `uvx` with no manual installation required
- Configuration requires editing JSON files for Claude Desktop ([`claude_desktop_config.json`](https://github.com/lfnovo/open-notebook/blob/main/claude_desktop_config.json)) or VS Code ([`.vscode/mcp.json`](https://github.com/lfnovo/open-notebook/blob/main/.vscode/mcp.json))
- Two environment variables control the connection: `OPEN_NOTEBOOK_URL` and `OPEN_NOTEBOOK_PASSWORD`
- The integration exposes full CRUD operations for notebooks, sources, notes, plus chat, search, and model management
- For remote deployments, update the URL to point to your hosted instance and verify firewall rules

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) in Open Notebook?

The Model Context Protocol is an open standard that enables AI applications like Claude Desktop and VS Code extensions to communicate directly with the Open Notebook API. It acts as a bridge that exposes your notebook data and operations to AI assistants as callable tools.

### Do I need to manually install the open-notebook-mcp package?

No manual installation is required. According to the lfnovo/open-notebook source code in [`docs/5-CONFIGURATION/mcp-integration.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/mcp-integration.md), Claude Desktop and VS Code extensions automatically invoke the server using the `uvx open-notebook-mcp` command. The `uvx` tool handles the package download and execution transparently.

### Where do I configure the MCP integration for different clients?

For **Claude Desktop**, edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. For **VS Code**, create or edit [`.vscode/mcp.json`](https://github.com/lfnovo/open-notebook/blob/main/.vscode/mcp.json) in your workspace or use the global settings. Both use the same JSON structure with `command`, `args`, and `env` fields.

### Why is my MCP connection failing after configuration?

Connection failures typically occur when `OPEN_NOTEBOOK_URL` does not point to a running FastAPI instance (check that port 5055 is accessible), when the password in `OPEN_NOTEBOOK_PASSWORD` does not match the value set in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py), or when firewall rules block the connection to remote servers. Verify these settings and restart your client application.