How to add Ebook-MCP to Windsurf
Chat with your EPUB and PDF books — extract metadata, table of contents, chapters, and pages as Markdown. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.
Last updated June 14, 2026 · 372★ · stdio · no auth
Windsurf config for Ebook-MCP
uv pip install -e .{
"mcpServers": {
"ebook-mcp": {
"command": "uv",
"args": [
"--directory",
"/Users/onebird/github/ebook-mcp/src/ebook_mcp/",
"run",
"main.py"
]
}
}
}Setup steps
- 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
- 2Paste the Ebook-MCP config below.
- 3Fill in placeholder secrets, then save.
- 4Click Refresh in the MCP panel.
- 5Ebook-MCP's tools become available to Cascade.
Before you start
- Python with the uv package manager installed
- The repository cloned locally (the Cursor config points at the local src/ebook_mcp path)
- Dependencies installed via 'uv pip install -e .'
What Ebook-MCP can do in Windsurf
get_all_epub_filesGet all EPUB files in the specified directory. Signature: get_all_epub_files(path: str) -> List[str].
get_metadataGet metadata (title, author, publication date, etc.) from an EPUB file. Signature: get_metadata(epub_path: str) -> Dict[str, Union[str, List[str]]].
get_tocGet the table of contents from an EPUB file. Signature: get_toc(epub_path: str) -> List[Tuple[str, str]].
get_chapter_markdownGet chapter content from an EPUB file in Markdown format. Chapter IDs come from the table of contents structure. Signature: get_chapter_markdown(epub_path: str, chapter_id: str) -> str.
get_all_pdf_filesGet all PDF files in the specified directory. Signature: get_all_pdf_files(path: str) -> List[str].
get_pdf_metadataGet metadata (title, author, creation date, etc.) from a PDF file. Signature: get_pdf_metadata(pdf_path: str) -> Dict[str, Union[str, List[str]]].
get_pdf_tocGet the table of contents from a PDF file. Signature: get_pdf_toc(pdf_path: str) -> List[Tuple[str, int]].
get_pdf_page_textGet plain text content from a specific page of a PDF. Signature: get_pdf_page_text(pdf_path: str, page_number: int) -> str.
Security
Runs locally over stdio and reads files from paths you provide; no authentication or remote service is involved. The server reads ebook files from the local filesystem, so only point it at directories you trust. PDF features rely on the document's embedded table of contents and may not work when a TOC is absent.
Ebook-MCP + Windsurf FAQ
Where is the Windsurf config file?
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Ebook-MCP config there under the "mcpServers" key and restart the client.
Is Ebook-MCP safe to use with Windsurf?
Runs locally over stdio and reads files from paths you provide; no authentication or remote service is involved. The server reads ebook files from the local filesystem, so only point it at directories you trust. PDF features rely on the document's embedded table of contents and may not work when a TOC is absent.
Which ebook formats are supported?
EPUB and PDF. The README states more formats may be added over time, but the documented tools currently cover EPUB and PDF.
How do I configure it in Cursor?
Add an 'ebook-mcp' entry whose command is 'uv' with args '--directory <path-to>/src/ebook_mcp/ run main.py'. Update the directory to the location where you cloned the repository.
Why do some PDF features not work?
PDF processing relies on the document's embedded table of contents. If a PDF has no TOC, chapter-based extraction may not work. For large PDFs, process by page ranges to avoid loading the entire file at once.