{
  "markdown": "# Open Notebook MCP Server\n\n<!-- mcp-name: io.github.Epochal-dev/open-notebook -->\n\nAn MCP (Model Context Protocol) server that provides tools to interact with the [Open Notebook](https://github.com/lfnovo/open-notebook) API. This server enables AI assistants like Claude to manage notebooks, sources, notes, search content, and interact with AI models through Open Notebook.\n\n## Features\n\n- **Notebooks Management**: Create, read, update, and delete notebooks\n- **Sources Management**: Add and manage content sources (links, uploads, text)\n- **Notes Management**: Create and organize notes within notebooks\n- **Search & AI**: Search content using vector/text search and ask questions\n- **Models Management**: Configure and manage AI models\n- **Chat Sessions**: Create and manage chat conversations\n- **Settings**: Access and update application settings\n- **Progressive Disclosure**: Efficient tool discovery with `search_capabilities`\n\n## Installation\n\n### Using uv (recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/PiotrAleksander/open-notebook-mcp.git\ncd open-notebook-mcp\n\n# Install with uv\nuv sync\n```\n\n### Using pip\n\n```bash\npip install -e .\n```\n\n## Configuration\n\nThe server requires configuration to connect to your Open Notebook instance:\n\n### Environment Variables\n\nCreate a `.env` file or set these environment variables:\n\n```bash\n# Required: URL of your Open Notebook instance\nOPEN_NOTEBOOK_URL=http://localhost:5055\n\n# Optional: Authentication password (if APP_PASSWORD is set in Open Notebook)\nOPEN_NOTEBOOK_PASSWORD=your_password_here\n\n# Optional: Transport configuration (default: stdio)\nMCP_TRANSPORT=stdio  # or streamable-http for remote deployment\n```\n\n### Example Configuration\n\nFor local development with default Open Notebook settings:\n\n```bash\n# .env\nOPEN_NOTEBOOK_URL=http://localhost:5055\n```\n\nIf you've configured authentication in Open Notebook:\n\n```bash\n# .env\nOPEN_NOTEBOOK_URL=http://localhost:5055\nOPEN_NOTEBOOK_PASSWORD=my_secure_password\n```\n\n## Usage\n\n### Running the Server\n\n#### Development Mode (STDIO)\n\nFor local use with AI assistants:\n\n```bash\nuv run open-notebook-mcp\n```\n\nOr using the MCP CLI:\n\n```bash\nmcp dev src/open_notebook_mcp/server.py\n```\n\n#### Production Mode (Streamable HTTP)\n\nFor remote deployment:\n\n```bash\nMCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uv run open-notebook-mcp\n```\n\n### Using with Claude Desktop\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"open-notebook\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/open-notebook-mcp\",\n        \"open-notebook-mcp\"\n      ],\n      \"env\": {\n        \"OPEN_NOTEBOOK_URL\": \"http://localhost:5055\",\n        \"OPEN_NOTEBOOK_PASSWORD\": \"your_password_if_needed\"\n      }\n    }\n  }\n}\n```\n\n### Discovering Available Tools\n\nThe server implements progressive disclosure. Use the `search_capabilities` tool to discover available functionality:\n\n```python\n# Get a summary of all tools\nsearch_capabilities(query=\"\", detail=\"summary\", limit=50)\n\n# Search for specific functionality\nsearch_capabilities(query=\"notebook\", detail=\"summary\", limit=10)\n\n# Get full details for a specific tool\nsearch_capabilities(query=\"create_notebook\", detail=\"full\", limit=1)\n```\n\n### Example Workflows\n\n#### Creating and Managing Notebooks\n\n```python\n# Create a new notebook\nresult = create_notebook(\n    name=\"AI Research\",\n    description=\"Research on AI applications\"\n)\nnotebook_id = result[\"notebook\"][\"id\"]\n\n# List all notebooks\nnotebooks = list_notebooks(archived=False, limit=20)\n\n# Update a notebook\nupdate_notebook(\n    notebook_id=notebook_id,\n    name=\"AI Research (Updated)\"\n)\n\n# Get a specific notebook\nnotebook = get_notebook(notebook_id=notebook_id)\n```\n\n#### Adding Sources\n\n```python\n# Add a web source\nsource = create_source(\n    notebook_id=notebook_id,\n    type=\"link\",\n    url=\"https://example.com/ai-article\",\n    title=\"AI Research Article\",\n    embed=True  # Generate embeddings\n)\n\n# List sources in a notebook\nsources = list_sources(notebook_id=notebook_id, limit=20)\n```\n\n#### Creating Notes\n\n```python\n# Create a note\nnote = create_note(\n    notebook_id=notebook_id,\n    title=\"Key Findings\",\n    content=\"Important insights about AI applications...\",\n    topics=[\"AI\", \"Research\"]\n)\n\n# Update a note\nupdate_note(\n    note_id=note[\"note\"][\"id\"],\n    content=\"Updated insights...\"\n)\n```\n\n#### Searching and Asking Questions\n\n```python\n# Search content\nresults = search(\n    query=\"artificial intelligence\",\n    type=\"vector\",\n    notebook_id=notebook_id,\n    limit=10\n)\n\n# List available models first\nmodels = list_models(limit=50)\nmodel_id = models[\"models\"][0][\"id\"]\n\n# Ask a question\nanswer = ask_simple(\n    question=\"What are the main AI applications mentioned?\",\n    strategy_model=model_id,\n    answer_model=model_id,\n    final_answer_model=model_id,\n    notebook_id=notebook_id\n)\n```\n\n#### Chat Sessions\n\n```python\n# Create a chat session\nsession = create_chat_session(\n    notebook_id=notebook_id,\n    title=\"Research Discussion\"\n)\nsession_id = session[\"session\"][\"id\"]\n\n# Build context\ncontext = get_chat_context(notebook_id=notebook_id)\n\n# Send a message\nresponse = execute_chat(\n    session_id=session_id,\n    message=\"What are the key insights from my research?\",\n    context=context[\"context\"]\n)\n\n# Get session history\nhistory = get_chat_session(session_id=session_id)\n```\n\n## Available Tools\n\nThe server provides 39 tools across multiple categories:\n\n### Meta Tools\n\n- `search_capabilities` - Progressive tool discovery\n\n### Notebooks (5 tools)\n\n- `list_notebooks`, `get_notebook`, `create_notebook`, `update_notebook`, `delete_notebook`\n\n### Sources (5 tools)\n\n- `list_sources`, `get_source`, `create_source`, `update_source`, `delete_source`\n\n### Notes (5 tools)\n\n- `list_notes`, `get_note`, `create_note`, `update_note`, `delete_note`\n\n### Search (3 tools)\n\n- `search`, `ask_question`, `ask_simple`\n\n### Models (5 tools)\n\n- `list_models`, `get_model`, `create_model`, `delete_model`, `get_default_models`\n\n### Chat (7 tools)\n\n- `list_chat_sessions`, `create_chat_session`, `get_chat_session`, `update_chat_session`, `delete_chat_session`, `execute_chat`, `get_chat_context`\n\n### Settings (2 tools)\n\n- `get_settings`, `update_settings`\n\n## Architecture\n\nThis server follows MCP best practices:\n\n- **Progressive Disclosure**: Use `search_capabilities` to minimize context usage\n- **Context Efficiency**: Small outputs by default, with limit parameters\n- **Dual Transport**: Supports both STDIO (local) and Streamable HTTP (remote)\n- **Error Handling**: Structured error messages with actionable hints\n- **Timeouts**: 30-second default timeout for all API requests\n- **Authentication**: Optional Bearer token authentication\n\n## Development\n\n### Project Structure\n\n```\nopen-notebook-mcp/\n├── src/\n│   └── open_notebook_mcp/\n│       ├── __init__.py\n│       └── server.py          # Main MCP server implementation\n├── tests/                      # (to be added)\n├── pyproject.toml\n├── README.md\n└── .env.example\n```\n\n### Testing\n\nTest the server using the MCP Inspector:\n\n```bash\nmcp dev src/open_notebook_mcp/server.py\n```\n\nor\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory ./src/open_notebook_mcp \"run\" \"server.py\"\n```\n\nThis opens an interactive inspector where you can:\n\n1. Browse available tools\n2. Test tool calls\n3. Inspect responses\n4. Debug errors\n\n### Adding New Tools\n\nTo add new tools:\n\n1. Add a `Capability` entry to the `CAPABILITIES` tuple\n2. Implement the tool function with `@mcp.tool()` decorator\n3. Follow naming conventions: `verb_noun` (e.g., `list_notebooks`)\n4. Include proper docstrings and type hints\n5. Return structured responses with `request_id`\n\n## Requirements\n\n- Python 3.12+\n- Open Notebook instance (local or remote)\n- Dependencies: `mcp[cli]>=1.23.2`, `httpx>=0.28.1`\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n- Follow the existing code structure and patterns\n- Add tools to the `CAPABILITIES` index\n- Include proper type hints and docstrings\n- Test with MCP Inspector before submitting\n\n## License\n\nSee LICENSE file for details.\n\n## Links\n\n- [Open Notebook](https://github.com/lfnovo/open-notebook)\n- [Open Notebook API Reference](https://github.com/lfnovo/open-notebook/blob/main/docs/development/api-reference.md)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [FastMCP Documentation](https://gofastmcp.com/)\n\n## Support\n\nFor issues related to:\n\n- **This MCP server**: Open an issue in this repository\n- **Open Notebook itself**: Visit the [Open Notebook repository](https://github.com/lfnovo/open-notebook)\n- **MCP protocol**: Check the [MCP documentation](https://modelcontextprotocol.io/)\n",
  "bytes": 8780,
  "sha": "852fab5db1fc861d7e2db580b87055c9337143451168341637a03b7293be85b2",
  "repo_slug": "epochal-dev/open-notebook-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_piotraleksander_open_notebook_e328ce31/readme"
}