Gallica/BnF MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gallica/BnF MCP Server search for documents by Victor Hugo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Node.js MCP Server for Gallica/BnF
A high-quality TypeScript/Node.js MCP (Model Context Protocol) server for accessing the Gallica digital library of the Bibliothèque nationale de France (BnF). This server faithfully reproduces all functionality from the Python MCP server and extends it with additional features for IIIF images, OCR text, and item metadata.
Features
Core Search Tools (8 tools - matching Python)
search_by_title - Search documents by title with exact match option
search_by_author - Search documents by author with exact match option
search_by_subject - Search documents by subject with exact match option
search_by_date - Search documents by date (YYYY, YYYY-MM, or YYYY-MM-DD)
search_by_document_type - Search by document type (monographie, periodique, image, etc.)
advanced_search - Custom CQL query syntax for complex searches
natural_language_search - Natural language search across all fields
sequential_reporting - Multi-step sequential report generation with source management
Extended Tools (4 new tools)
get_item_details - Get full metadata for an item by ARK identifier
get_item_pages - Enumerate pages of a document with IIIF URLs
get_page_image - Generate IIIF image URLs for specific pages
get_page_text - Retrieve OCR/text content (ALTO, plain text)
Related MCP server: gallica-mcp
Installation
Prerequisites
Node.js 18.0 or higher
npm or yarn
Steps
Clone or download this repository
Install dependencies:
cd node-mcp-bnf npm installBuild the project:
npm run build
Usage
Local Development
Option 1: HTTP Server (Recommended for Development)
Run the server on a local HTTP port for testing:
npm run dev:httpThis starts the server on http://localhost:3000 (or the port specified in PORT environment variable).
The server will:
Listen on the specified port
Accept MCP requests via HTTP/SSE
Log all activity to the console
You can test it by connecting an MCP client to http://localhost:3000/message.
Option 2: STDIO Mode (For MCP Clients)
The server can be used locally with Claude Desktop or Cursor MCP via STDIO.
Run in STDIO mode:
npm run devClaude Desktop Configuration
Add to your Claude Desktop configuration file (usually ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"gallica-bnf": {
"command": "node",
"args": ["/path/to/node-mcp-bnf/dist/index.js"],
"cwd": "/path/to/node-mcp-bnf"
}
}
}Cursor MCP Configuration
Add to your Cursor MCP settings:
{
"mcpServers": {
"gallica-bnf": {
"command": "node",
"args": ["/path/to/node-mcp-bnf/dist/index.js"]
}
}
}Development Scripts
npm run dev- Run in STDIO mode (for MCP clients like Cursor/Claude Desktop)npm run dev:http- Run HTTP server on local port (default: 3000)npm start- Run compiled STDIO versionnpm run start:http- Run compiled HTTP server version
Environment Variables for HTTP Server:
PORT- Port to listen on (default: 3000)LOG_LEVEL- Logging level (error, warn, info, debug)
Deployment on Vercel
Prerequisites
Vercel account
Vercel CLI installed (
npm i -g vercel)
Steps
Create
vercel.jsonin project root:{ "functions": { "src/httpServer.ts": { "runtime": "nodejs18.x" } }, "routes": [ { "src": "/(.*)", "dest": "src/httpServer.ts" } ] }Set environment variables in Vercel dashboard:
GALLICA_BASE_URL(optional, default:https://gallica.bnf.fr)GALLICA_SRU_URL(optional, default:https://gallica.bnf.fr/SRU)LOG_LEVEL(optional, default:info)MCP_ICON_URL(optional, absolute URL to icon - defaults to/icon.svgrelative to server URL)
Deploy:
vercel deployConfigure Cursor/Claude Desktop to use HTTP endpoint:
{ "mcpServers": { "gallica-bnf": { "url": "https://your-vercel-app.vercel.app" } } }
API Documentation
Search Tools
search_by_title
Search for documents by title.
Parameters:
title(string, required): The title to search forexact_match(boolean, optional): If true, search for exact titlemax_results(number, optional, default: 10): Maximum results (1-50)start_record(number, optional, default: 1): Starting record for pagination
Example:
{
"title": "Les Misérables",
"exact_match": false,
"max_results": 10
}search_by_author
Search for documents by author.
Parameters:
author(string, required): The author nameexact_match(boolean, optional): If true, search for exact author namemax_results(number, optional, default: 10)start_record(number, optional, default: 1)
search_by_subject
Search for documents by subject/keywords.
Parameters:
subject(string, required): The subject to search forexact_match(boolean, optional)max_results(number, optional, default: 10)start_record(number, optional, default: 1)
search_by_date
Search for documents by publication date.
Parameters:
date(string, required): Date in format YYYY, YYYY-MM, or YYYY-MM-DDmax_results(number, optional, default: 10)start_record(number, optional, default: 1)
Example:
{
"date": "1862",
"max_results": 20
}search_by_document_type
Search for documents by type.
Parameters:
doc_type(string, required): Document type (monographie, periodique, image, manuscrit, carte, musique, etc.)max_results(number, optional, default: 10)start_record(number, optional, default: 1)
advanced_search
Perform advanced search with custom CQL query.
Parameters:
query(string, required): CQL query stringmax_results(number, optional, default: 10)start_record(number, optional, default: 1)
Example:
{
"query": "dc.creator all \"Victor Hugo\" and dc.type all \"monographie\""
}natural_language_search
Natural language search across all fields.
Parameters:
query(string, required): Natural language search querymax_results(number, optional, default: 10)start_record(number, optional, default: 1)
Extended Tools
get_item_details
Get full metadata for an item.
Parameters:
ark(string, required): ARK identifier (e.g., "ark:/12148/bpt6k123456" or "bpt6k123456")
Returns:
Bibliographic data (title, creator, date, etc.)
Available formats (iiif, image, text, alto)
IIIF manifest URL
Gallica URL
get_item_pages
Enumerate pages of a document.
Parameters:
ark(string, required): ARK identifierpage(number, optional): Get specific page numberpage_size(number, optional): Get first N pagespage_range(array, optional): Get pages in range [start, end]
Returns:
Array of page info with:
Page number
Label
IIIF image URL
Text availability flag
Thumbnail URL
get_page_image
Get IIIF image URL for a specific page.
Parameters:
ark(string, required): ARK identifierpage(number, required): Page numbersize(string, optional): Image size (e.g., "full", "200,", "500,500")region(string, optional): Image region (e.g., "full", "x,y,w,h")
Returns:
IIIF image URL
Thumbnail URL
get_page_text
Retrieve OCR/text content for a page.
Parameters:
ark(string, required): ARK identifierpage(number, required): Page numberformat(string, optional): "plain" (default) or "alto" — both return plain text extracted from the page's ALTO OCR. "tei" is not available per page. Gallica's.texteBrutendpoint is not used: it redirects automated clients to an anti-bot challenge.
Returns:
Text content (or null if not available)
Availability flag
Sequential Reporting Tool
sequential_reporting
Generate research reports in a sequential, step-by-step manner.
Workflow:
Initialize:
{ "topic": "Impressionnisme en France", "page_count": 4, "source_count": 10, "include_graphics": true }Search sources:
{ "search_sources": true }Create bibliography:
{ "section_number": 1, "total_sections": 8, "title": "Bibliography", "content": "...", "is_bibliography": true, "sources_used": [1, 2, 3], "next_section_needed": true }Write sections sequentially:
{ "section_number": 2, "total_sections": 8, "title": "Introduction", "content": "...", "sources_used": [1, 2], "next_section_needed": true }Complete report:
{ "section_number": 8, "total_sections": 8, "title": "Conclusion", "content": "...", "sources_used": [5, 6], "next_section_needed": false }
Configuration
Environment Variables
GALLICA_BASE_URL- Base URL for Gallica API (default:https://gallica.bnf.fr)GALLICA_SRU_URL- SRU search endpoint (default:https://gallica.bnf.fr/SRU)LOG_LEVEL- Logging level:error,warn,info,debug(default:info)HTTP_TIMEOUT- Timeout per HTTP attempt in milliseconds (default: 45000)HTTP_RETRIES- Retries for transient failures only: network errors, 429, 502-504 (default: 1)HTTP_DEADLINE- Total time budget per Gallica call, including queueing and retries, in ms (default: 55000)GALLICA_MIN_INTERVAL_MS- Minimum spacing between requests to Gallica; requests are sent one at a time (default: 1000)GALLICA_CACHE_TTL_MS- How long successful Gallica responses are cached in memory (default: 600000)
Gallica blocks IP addresses that send bursts of requests (first TCP resets, then
403 Access Denied). Keep the request interval at 1s or more, especially on shared hosting such as Vercel. Throttling and caching are per server instance.
DEFAULT_MAX_RECORDS- Default maximum search results (default: 10)DEFAULT_START_RECORD- Default starting record for pagination (default: 1)
Development
Project Structure
node-mcp-bnf/
├── src/
│ ├── index.ts # STDIO entry point
│ ├── httpServer.ts # HTTP entry point
│ ├── mcpServer.ts # MCP server setup
│ ├── config.ts # Configuration
│ ├── logging.ts # Logging utility
│ ├── tools/ # MCP tools
│ └── gallica/ # Gallica API clients
├── docs/ # Documentation
├── tests/ # Unit tests
└── package.jsonBuilding
npm run buildTesting
npm testDevelopment Mode
npm run devDocumentation
Python Architecture Analysis - Analysis of the original Python server
Gallica API Notes - Detailed API documentation
Node.js Architecture - Architecture and design of this server
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Acknowledgments
Based on the Python MCP server by Kryzo
Uses the Model Context Protocol SDK
Built for the Gallica digital library of the Bibliothèque nationale de France
Available Tools
12 toolsadvanced_searchC
Perform an advanced search using custom CQL query syntax. Examples: dc.creator all "Victor Hugo" and dc.type all "monographie", dc.subject all "Paris" and dc.type all "carte", dc.language all "eng".
Inputs: query (required), max_results, start_record.
get_item_detailsA
Get full metadata for a Gallica item by its ARK identifier. Returns bibliographic data, available formats, and helpful URLs.
Inputs: ark (required).
get_item_pagesB
Enumerate pages of a document. Returns logical page numbers, IIIF image URLs, and text availability flags.
Inputs: ark (required), page, page_size, page_range.
get_page_imageA
Get IIIF image URL for a specific page. Returns URL and metadata, not binary data.
Inputs: ark (required), page (required), size, region.
get_page_textA
Retrieve OCR or TEI text for a specific page when available. Returns null if text is not available.
Inputs: ark (required), page (required), format.
natural_language_searchB
Search the Gallica digital library using natural language. This is a simplified search that uses the "gallica all" operator to search across all fields.
Inputs: query (required), max_results, start_record.
search_by_authorC
Search for documents in the Gallica digital library by author.
Inputs: author (required), exact_match, max_results, start_record.
search_by_dateC
Search for documents in the Gallica digital library by date. Accepts YYYY, YYYY-MM, or YYYY-MM-DD format.
Inputs: date (required), max_results, start_record.
search_by_document_typeB
Search for documents in the Gallica digital library by document type (e.g., monographie, periodique, image, manuscrit, carte, musique, etc.).
Inputs: doc_type (required), max_results, start_record.
search_by_subjectC
Search for documents in the Gallica digital library by subject.
Inputs: subject (required), exact_match, max_results, start_record.
search_by_titleC
Search for documents in the Gallica digital library by title.
Inputs: title (required), exact_match, max_results, start_record.
sequential_reportingB
Generate a research report in a sequential, step-by-step manner using Gallica BnF sources.
This tool follows a sequential approach to report generation:
Initialize with a topic
Search for sources
Create bibliography
Create content sections in order
Parameters:
topic: Research topic (only needed for initialization)
page_count: Number of pages for the report (default: 4)
source_count: Number of sources to find (default: 10)
search_sources: Set to true to search for sources after initialization
section_number: Current section number (1-based)
total_sections: Total number of sections in the report
title: Title of the current section
content: Content for the current section
is_bibliography: Whether this section is the bibliography
sources_used: List of source IDs used in this section
next_section_needed: Whether another section is needed
include_graphics: Whether to include images and maps in the report
Inputs: section_number (required), total_sections (required), title (required), content (required), +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have distinct purposes, but there is significant overlap between the six specific search tools (search_by_author, search_by_title, etc.) and the general natural_language_search and advanced_search tools, which could cause confusion about when to use each. The sequential_reporting tool stands out as a high-level workflow tool that might be misapplied instead of using the underlying search and retrieval tools directly.
The naming is mostly consistent with a verb_noun pattern (e.g., get_item_details, search_by_author), but there are minor deviations: advanced_search uses an adjective instead of a verb, and sequential_reporting uses an adjective rather than a verb, breaking the pattern slightly. Overall, the naming is readable and follows a clear convention.
With 12 tools, the count is reasonable for a digital library server, covering search, retrieval, and reporting functions. It is slightly on the higher side but well-scoped for the domain, as it includes multiple search facets and detailed item handling, without being overwhelming.
The tool set provides strong coverage for searching and retrieving documents, including metadata, pages, images, and text. However, there are minor gaps: no tools for user account management (e.g., saving favorites or history) or batch operations (e.g., downloading multiple items), which might be useful for advanced research workflows but are not essential for core functionality.
Related MCP Connectors
Resolve, search and verify legal citations against the official sources, with provenance.
Search the Wayback Machine and IA library (40M+ items), fetch snapshots, item metadata, and text.
French case law (Judilibre) and codes (Légifrance) from official sources, with citation checking.
Search, read and cite documents. Add, replace and delete files with write access. OAuth required.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model-Client-Protocol server that enables users to search the Gallica digital library of the National Library of France and generate structured sequential research reports with formatted citations and relevant images.13-
- AlicenseAqualityCmaintenanceEnables searching and accessing OCR text from millions of digitized documents in Gallica, the digital library of the Bibliothèque nationale de France, through MCP tools for text search, snippet retrieval, and full-text download.31Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables searching documents in Gallica, the digital library of the Bibliothèque nationale de France, and generating structured research reports with citations and images.-
- AlicenseNot gradedqualityCmaintenanceEnables searching and retrieving documents from the French national open research archive HAL, including author and research structure lookups.141 npmMIT