Cookbook Shelf

A small read-only Python CLI and MCP server for listing cookbooks on your Eat Your Books shelf and finding recipe references in those books.

Status: experimental; live CLI and MCP checks passed using regular Chrome attachment. Manually signing into a dedicated Chrome window, then connecting with EYB_CDP_URL, successfully listed the test account's full book inventory and searched its recipes across multiple pages. Version 0.2.1 also fixes Unicode output when a Windows CLI command is piped or redirected. There are 54 automated tests; see VALIDATION.md for the live checks and their limits.

The original Playwright-launched login still stalls on Cloudflare. The verified path is Attach to regular Chrome, below. An in-app browser login does not automatically sign this separate Chrome profile in.

Install

Requires Python 3.10+ and a supported desktop browser environment.

From this directory, with uv:

uv sync --extra mcp

Or with pip:

python -m pip install ".[mcp]"

After installation, follow Attach to regular Chrome below. Installed Google Chrome is sufficient for attachment; python -m playwright install chromium is only necessary for the original launcher mode. With uv, prefix cookbooks commands below with uv run.

In the original launcher mode (without EYB_CDP_URL), login opens a dedicated browser window. Sign in on EYB yourself, then press Enter in the terminal. Session cookies stay in that local browser profile. The tool does not ask for, log, or store your password in its configuration. It does not solve CAPTCHAs, use stealth plugins, or bypass access checks. If EYB blocks this browser, the tool reports that and stops; a browser-backed adapter is not guaranteed to avoid verification challenges.

Version 0.1.1 explicitly enables Chromium's sandbox, correcting the original launcher's --no-sandbox warning. This fixes a browser setting; it is not a Cloudflare fix. If verification stays on screen for about a minute, cancel in the terminal with Ctrl+C (or type q). If you press Enter while still challenged, the tool reports the block without making another navigation request. Cloudflare lists automated browsers as unsupported for production challenges.

Related MCP server: mealie-mcp

Attach to regular Chrome (verified on the test account)

This option does not need a browser extension. Start Chrome yourself with a dedicated data directory and a local debugging port. On Windows, for example:

$env:EYB_PROFILE_DIR = Join-Path $env:LOCALAPPDATA 'cookbook-shelf\manual-chrome-profile'
$env:EYB_CDP_URL = 'http://127.0.0.1:9223'
$eybChrome = Join-Path $env:ProgramFiles 'Google\Chrome\Application\chrome.exe'
& $eybChrome "--user-data-dir=$env:EYB_PROFILE_DIR" --remote-debugging-address=127.0.0.1 --remote-debugging-port=9223 https://www.eatyourbooks.com/myhome

Sign in and reach your Bookshelf before running the CLI. Leave Chrome open. Use this dedicated profile only for EYB. The local debugging endpoint controls that browser; do not expose it on your network or use your everyday Chrome profile.

In the same terminal (after installing the package), run:

cookbooks --json login
cookbooks --json list
cookbooks --json search --ingredient edamame --max-pages 6

With EYB_CDP_URL set, login only verifies access; it never opens a sign-in form or asks for a password. Queries create and close their own temporary tab in the existing browser context. They do not close Chrome or the tab you used to sign in. --headed and EYB_BROWSER_CHANNEL apply only to launcher mode. --profile / EYB_PROFILE_DIR coordinates command locking in attachment mode; the attached browser itself determines the account and cookie profile.

You can also pass --cdp-url http://127.0.0.1:9223 before a CLI subcommand. Only HTTP endpoints at explicit loopback IP addresses and ports are accepted. MCP uses the same EYB_CDP_URL and EYB_PROFILE_DIR environment variables; the browser must already be open and signed in. No session credentials are copied. If a query is challenged, it stops. This is not a guarantee that EYB will accept automated searches after manual login.

Use

uv run cookbooks list
uv run cookbooks search --ingredient edamame
uv run cookbooks search --dish salsa
uv run cookbooks search --query '"Ina Garten" chicken'
uv run cookbooks --json search --ingredient edamame
uv run cookbooks --headed search --dish salsa

Global switches (--json, --headed, --profile, --cdp-url, --demo) go before the subcommand. Commands return exit code 2 for an actionable error and 130 on cancel.

• Ingredient searches quote the phrase in EYB's search and then match it against listed ingredients. This avoids treating every broader soybean match as edamame. Use one ingredient phrase per query; for several ingredients use --query with EYB's normal search syntax. Synonyms are not silently invented.

• Dish searches quote the phrase, then check titles and categories. Results may include "chicken with salsa" as well as standalone salsa recipes. This is candidate discovery, not exhaustive taxonomy classification.

• Keyword passes the query to EYB and retains results whose source book ID is on your shelf. EYB supports exact phrases, exclusions, and title: queries.

• Results preserve recipe and book links, authors, page numbers, ingredients, and categories when available. Unknown values stay null.

• All searches first obtain your book inventory and restrict results to those IDs. Bookshelf navigation is used exclusively; there is no global-library fallback and no book, bookmark, or note mutation endpoint.

• Book lists use the 200-entry condensed view. Recipe searches use the detailed view because condensed recipe lists omit ingredient metadata. On a mobile layout the parser also reads metadata beneath the expandable result.

• Pagination follows EYB's next links, with a one-second minimum interval between navigation requests. It stops at limits, repeated pages, redirects to other searches, login pages, and verification/rate-limit responses. Where EYB displays a result count, the tool checks it against the records traversed before claiming completion.

Defaults: up to 500 books or 200 matching recipes, and 20 pages per listing. When limited, output explicitly says PARTIAL / truncated: true.

uv run cookbooks --json search --dish salsa --limit 1000 --max-pages 50

search_pages_complete means the returned EYB query pages were traversed. It does not mean that every physical book was fully searchable. Check indexing coverage and missing-metadata warnings. Unindexed books and incomplete indexes cannot supply all of their recipes. No quantities, methods, or dietary safety guarantees are inferred from index data.

Try without an account

uv run cookbooks --demo list
uv run cookbooks --demo search --ingredient edamame
uv run cookbooks --demo --json search --dish salsa

Demo content is fictional and labeled as such. Demo mode makes no network calls and does not start a browser.

MCP

The MCP interface uses the same service as the CLI. Two tools are exposed:

• list_cookbooks(limit=500, max_pages=20)

• search_my_recipes(query, mode="keyword", limit=200, max_pages=20)

Both are annotated read-only. No credentials are accepted as tool arguments. Login is performed separately in a terminal. Calls are serialized so the same profile cannot be driven concurrently. In attachment mode each operation closes only its own query tab and disconnects; Chrome remains open. In launcher mode it closes its browser. Protocol output uses stdout; browser/login issues are tool errors.

Example Codex configuration (replace the directory with this project's actual absolute path and use the same local OS account as cookbooks login):

[mcp_servers.cookbook_shelf]
command = "uv"
args = ["--directory", "/absolute/path/to/cookbook-shelf", "run", "--extra", "mcp", "cookbook-shelf-mcp"]
tool_timeout_sec = 180

[mcp_servers.cookbook_shelf.env]
EYB_CDP_URL = "http://127.0.0.1:9223"
EYB_PROFILE_DIR = "/absolute/path/to/dedicated-chrome-profile"

The local launcher does not need an OpenAI API key. Tool results are visible to the assistant and therefore to whichever model provider your MCP client uses.

Browser options

Environment variables are optional:

Do not point the tool at your normal browser profile. The default is %LOCALAPPDATA%/cookbook-shelf/browser-profile on Windows, the equivalent Application Support folder on macOS, or the XDG data folder on Linux. This profile contains session credentials. Keep it out of Git and shared folders. Use the same browser channel for login and subsequent queries.

Tests

uv sync --extra mcp --extra dev
uv run pytest

Tests exercise current-style mobile/condensed markup, recipe page numbers, ingredient matching, cookbook ownership, pagination, truncation, missing data, query encoding, expired sessions, verification pages, profile locking, CLI JSON, and MCP tool calls. They use synthetic fixtures rather than member data. See VALIDATION.md for the checks run and remaining limitations.

Origin and access terms

This implementation was written independently. The prior lampholder/eat-your-books wrapper was reviewed as a reference. It has no declared license and contains syntax errors, so none of its code was copied or vendored. The implementation also accounts for observed current differences: page numbers in recipe headings, metadata moved outside .book-data, and path-based pagination.

This project's MIT license covers our code, not EYB content or access rights. It is unaffiliated with Eat Your Books / CookShelf. EYB's terms restrict automated access and AI-related use; this implementation does not confer permission or resolve those restrictions. A user's normal browser session is an authentication mechanism, not an exemption. No database of EYB content is distributed here.

References: EYB search documentation, MCP Python SDK, Playwright Python.