# open-notebook

Bridges your AI agent with an Open Notebook instance to search records, store research sources, and manage notes. Useful for querying your personal knowledge base in editor sessions.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 47
- Author: Epochal-dev
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Epochal-dev/open-notebook-mcp
- Updated: 2025-12-22
- HTML: https://affpapa.org/en/nevibecode/mcp/open-notebook

## What it does

The server exposes 39 tools to control notebooks, source materials, notes, and chat sessions. It uses progressive discovery through `search_capabilities`, so the assistant retrieves tool definitions on demand instead of cluttering the prompt context.

It supports text queries, vector retrieval, and automated embedding generation for external web links. You can also configure model profiles and trigger Q&A workflows directly against indexed notebooks. Communication runs over stdio or Streamable HTTP.

Running this bridge requires a live Open Notebook deployment reachable at `OPEN_NOTEBOOK_URL`. Without an active server, requests fail after the built-in 30-second timeout.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `OPEN_NOTEBOOK_URL`, `OPEN_NOTEBOOK_PASSWORD` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add open-notebook -e OPEN_NOTEBOOK_URL=<OPEN_NOTEBOOK_URL> -e OPEN_NOTEBOOK_PASSWORD=<OPEN_NOTEBOOK_PASSWORD> -- uvx open-notebook-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from open-notebook-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add open-notebook --env OPEN_NOTEBOOK_URL=<OPEN_NOTEBOOK_URL> --env OPEN_NOTEBOOK_PASSWORD=<OPEN_NOTEBOOK_PASSWORD> -- uvx open-notebook-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from open-notebook-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "open-notebook": {
            "command": "uvx",
            "args": [
                "open-notebook-mcp"
            ],
            "env": {
                "OPEN_NOTEBOOK_URL": "<OPEN_NOTEBOOK_URL>",
                "OPEN_NOTEBOOK_PASSWORD": "<OPEN_NOTEBOOK_PASSWORD>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from open-notebook-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "open-notebook": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "open-notebook-mcp"
            ],
            "env": {
                "OPEN_NOTEBOOK_URL": "<OPEN_NOTEBOOK_URL>",
                "OPEN_NOTEBOOK_PASSWORD": "<OPEN_NOTEBOOK_PASSWORD>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from open-notebook-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e OPEN_NOTEBOOK_URL=<OPEN_NOTEBOOK_URL> -e OPEN_NOTEBOOK_PASSWORD=<OPEN_NOTEBOOK_PASSWORD> open-notebook uvx open-notebook-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from open-notebook-mcp <command>

## When to use it
- run semantic and keyword searches across stored notebook entries
- save web links and raw text with vector embeddings
- organize structured notes inside dedicated research notebooks
- manage chat sessions and conversational context via the API

## Example prompts
- Search the AI Research notebook for notes covering vector search
- Add `https://example.com/ai-article` as an embedded link source to the current notebook
- List all active chat sessions stored in Open Notebook

## Similar
- [Reactive Resume](https://affpapa.org/en/nevibecode/mcp/reactive-resume.md) — MCP server · ★ 44874
- [screenpipe](https://affpapa.org/en/nevibecode/mcp/screenpipe.md) — MCP server · ★ 22053
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12791
- [kaneo](https://affpapa.org/en/nevibecode/mcp/kaneo.md) — MCP server · ★ 9602
- [Mindwtr](https://affpapa.org/en/nevibecode/mcp/mindwtr.md) — MCP server · ★ 2318
- [Azure DevOps (ADO)](https://affpapa.org/en/nevibecode/mcp/azure-devops-ado.md) — MCP server · ★ 2067

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md