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

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 (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:

{
  "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

Configuring VS Code for MCP Integration

For VS Code MCP extensions, add a 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:

{
  "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:

{
  "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.

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 (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
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) or VS Code (.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, 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 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, or when firewall rules block the connection to remote servers. Verify these settings and restart your client application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}