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., "@kb-newspapers-mcp Search for 'kolera' in Swedish newspapers from 1850 to 1870."
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.
A Model Context Protocol (MCP) server that provides AI assistants (such as Claude Desktop, Antigravity, Cursor, and other MCP-compliant clients) with direct programmatic access to the National Library of Sweden's (Kungliga biblioteket / KB) digitized historical newspapers from the 17th century up to circa 1908–1910.
Built in Python using FastMCP and uv.
🔍 Full-Text Search (OCR): Search across more than 2.2 million historical newspaper pages with highlighted text snippets (<em>...</em>) indicating matches.
📅 Filtering & Sorting: Filter by year or date range (e.g. 1850 to 1880 or 1862-07-01), restrict searches to specific newspaper titles (e.g. Aftonbladet, Dagens Nyheter, Post- och Inrikes Tidningar, Göteborgsposten), and sort by relevance or publication date.
📈 Timeline & Distribution: Aggregate occurrences of a word, name, or event over time (by year) or across different publications.
🖼️ High-Resolution Images (IIIF): Construct direct image URLs for page previews and full-resolution scans using KB's IIIF Image API.
🔗 Web Link Resolution: Bidirectional lookup between internal dataset package IDs and public article pages on tidningar.kb.se and digitalt.kb.se.
🕊️ Fair-Usage & Resilience: Automated exponential backoff for HTTP 429/503 responses, friendly User-Agent headers, and sane pagination defaults.
Related MCP server: DHLAB MCP Server
Python 3.10+
uv (recommended package manager)
To install uv on any platform, refer to the official uv installation guide, or run:
Linux / macOS:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Via Pip:
pip install uvClone the repository:
git clone https://github.com/tobbaz/kb-newspapers-mcp.git
cd kb-newspapers-mcpRun the server locally:
uv run kb-newspapers-mcpExecute integration tests:
uv run python test_server.pyAdd the server to your claude_desktop_config.json:
{
"mcpServers": {
"kb-newspapers": {
"command": "uv",
"args": [
"run",
"--directory",
"<path-to-repo>/kb-newspapers-mcp",
"kb-newspapers-mcp"
]
}
}
}mcp_config.json){
"mcpServers": {
"kb-newspapers": {
"command": "uv",
"args": [
"run",
"--directory",
"<path-to-repo>/kb-newspapers-mcp",
"kb-newspapers-mcp"
]
}
}
}(Replace <path-to-repo> with the absolute path to where you cloned this repository.)
search_newspapersSearches OCR full text across digitized historical Swedish newspapers.
query (string, required): Keyword or phrase (e.g. "ångfartyg", "Carl von Linné", "August Strindberg").
from_date (optional): Start date ('YYYY-MM-DD' or year 'YYYY').
to_date (optional): End date ('YYYY-MM-DD' or year 'YYYY').
newspaper (optional): Filter by newspaper title (e.g. 'Aftonbladet', 'Dagens Nyheter').
sort_by (optional): 'relevance' (default), 'date_asc' (oldest first), or 'date_desc' (newest first).
limit (int, default 20, max 100): Number of hits to return.
offset (int, default 0): Pagination starting index.
max_snippets (int, default 5): Maximum text snippets to return per page.
get_newspaper_timelineRetrieves aggregation statistics for a search term over time or across publications.
query (string, required): Search term (e.g. 'kolera').
field (optional): Aggregation target: 'datePublished' (by year) or 'isPartOf' (by publication title).
search_in_issueSearches within an individual newspaper issue using IIIF Content Search to return exact quotes and bounding-box coordinates.
package_id (string, required): Issue package identifier (e.g. 'dark-37858').
query (string, required): Word or phrase to locate.
get_newspaper_page_imageGenerates IIIF image URLs and web links for a given newspaper page.
image_service_id (optional): IIIF service URL returned from search_newspapers.
package_id (optional): Issue package identifier (e.g. 'dark-30466').
page_number (int, default 1): Page number within the issue.
width (int, default 1200): Desired pixel width for preview images.
lookup_newspaper_idConverts bidirectionally between data.kb.se package IDs and public web URLs on tidningar.kb.se.
id_or_url (string, required): E.g. 'dark-37858' or 'https://tidningar.kb.se/dxqth86q2n2zwg9'.
Searching digitized newspapers from the 17th to early 20th century presents distinct challenges due to typography and historical spelling. Follow these general strategies for optimal results:
Most Swedish newspapers before the late 19th century were printed in Fraktur (blackletter). OCR systems frequently misidentify character shapes:
Long 's' (ſ): Often transcribed as f, S, or l (e.g. Hilpershausen scanned as HilperShauftn).
Vowel mutations & Ligatures: Characters with umlauts or ligatures (ä, ö, æ, oe) may be parsed phonetically or stripped.
Similar letterforms: c vs e, rn vs m, v vs u.
Swedish spelling was only standardized in the early 20th century. When searching names, places, or terms:
Wildcard search (*): Use stems (e.g. Hilp* or Söder*) to capture truncated OCR or spelling variants.
Boolean OR: Combine historical variations (e.g. Carlscrona OR Karlskrona, Gustaf OR Gustav, Capitain OR Kapten).
Stage 1 (Discovery): Run search_newspapers with your query and date limits. Note the package_id, issue date, and page number of promising hits.
Stage 2 (Deep Context): If the snippets returned in Stage 1 are truncated or lack key context (e.g. destination of a traveller, cause of death, or family connections), call search_in_issue(package_id="...", query="...") on the relevant issue to extract full verbatim sentences and surrounding text quotes.
Stage 3 (Visual Verification): Open the direct image link (images.preview_width or images.max) to examine the original scanned page if the OCR text is degraded.
Historical Scope: Digitized newspapers published before circa 1908–1910 are in the public domain and made available as open data via data.kb.se. Modern newspapers are protected by copyright and are not included in this open API.
Fair Use: The National Library implements rate throttling to ensure service availability. This server includes an identifying User-Agent and automated exponential backoff when encountering rate limits.
MIT License. Metadata and digitized content are provided by the National Library of Sweden (Kungliga biblioteket).
Generate direct image URLs and IIIF links for a specific newspaper page.
Args:
image_service_id: IIIF image service URL returned from search_newspapers (e.g. 'https://data.kb.se/iiif/3/dark-30466%2Fbib4345612_18620716_0_s_0003.jp2').
package_id: Package ID of the newspaper issue (e.g. 'dark-30466' or 'dark-37858').
page_number: Page number within the issue (e.g. 1, 3, 4).
part_number: Part/section number (default 1).
width: Desired pixel width for the preview image (e.g. 1200 for readable size, 300 for thumbnail).
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | ||
| package_id | No | ||
| page_number | No | ||
| part_number | No | ||
| image_service_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full disclosure burden. It clearly says the tool generates URLs/IIIF links and documents defaults, but it does not explicitly state that the operation is read-only, what happens on invalid input, or whether any network request is made to resolve the image. That is acceptable for a simple URL-generation tool but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is stated in one sentence, followed by a compact, well-organized argument list. Every line adds useful information and no filler or repetition is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and richly documented parameters, the description is nearly complete: it includes source context for the main input, defaults, and typical usages. The only gaps are explicit alternative routing and edge-case behavior, which are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description compensates fully by explaining each of the five parameters with a purpose and representative examples. It adds meaning well beyond the bare schema property names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Generate direct image URLs and IIIF links') tied to a concrete resource ('a specific newspaper page'), so an agent immediately knows what the tool produces. It is also clearly distinct from the sibling tools, which search newspapers, build timelines, or search within an issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by showing where the key input comes from ('image_service_id ... returned from search_newspapers') and gives realistic usage examples for parameters such as width. It does not explicitly state when not to use this tool or name alternatives, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the temporal or newspaper distribution statistics for a search term.
Useful to discover when an event was reported most frequently or which newspapers covered it.
Args:
query: Search term (e.g. 'kolera', 'ångbåt', 'Sveriges riksdag').
field: Aggregation target: 'datePublished' (distribution by year) or 'isPartOf' (distribution by newspaper title).
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | datePublished | |
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explains that the tool aggregates by year or newspaper title and is a read-style 'Get' operation. It doesn't discuss rate limits or corpus scope, but for a simple statistics tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a one-sentence definition, a usage line, and a clear Args list. No filler or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, read-only statistics tool with an output schema available, the description covers purpose, parameter semantics, and usage context. Nothing critical is missing for selecting and invoking it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: it defines 'query' with concrete examples and defines 'field' with its two allowed values and their meanings ('distribution by year' vs 'distribution by newspaper title').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the temporal or newspaper distribution statistics for a search term.' It also names the two aggregation targets, which clearly separates it from sibling search/image/lookup tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool ('discover when an event was reported most frequently or which newspapers covered it'), but it does not explicitly contrast with alternatives like search_newspapers or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert bidirectionally between the National Library's internal package ID (e.g. 'dark-37858')
and the public web URL on tidningar.kb.se (e.g. 'https://tidningar.kb.se/dxqth86q2n2zwg9').
Args:
id_or_url: A data.kb.se package ID, or a URL/ID from tidningar.kb.se.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_url | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses the conversion behavior but says nothing about error handling, read-only guarantees, or side effects. The description is a straightforward action statement without additional behavioral context, which is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences (plus an args line) and is front-loaded with the core action. Every sentence adds value, with no filler or repetition. The examples are concise and illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no nested objects) and has an output schema, so the description doesn't need to explain return values. The description fully explains the input format and bidirectional purpose, leaving no critical gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, but the description compensates by explicitly defining the parameter: 'A data.kb.se package ID, or a URL/ID from tidningar.kb.se' and providing concrete examples. This gives the agent clear guidance on what values to pass, exceeding the bare schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Convert') and resource (package IDs and web URLs), and clearly distinguishes the tool from siblings by naming the two formats involved. The bidirectional nature is explicit, leaving no ambiguity about what the tool accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you have an ID or URL and need the other form) and the examples clarify the expected inputs. However, it doesn't explicitly contrast with sibling tools or state exclusions, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search inside a specific newspaper issue to locate all occurrences of a word or phrase
with exact text lines and coordinates for image highlighting (IIIF Content Search).
Two-Stage Workflow Usage:
Use this tool as Stage 2 after 'search_newspapers' whenever a snippet is cut off or you need
the complete surrounding sentence (e.g. to uncover full names, occupations, causes of death,
travel origins/destinations, or accompanying persons).
Args:
package_id: The package ID of the newspaper issue (e.g. 'dark-37858').
query: Search word or phrase to locate within the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| package_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the purpose and hints at the output (text lines and coordinates), but does not disclose potential limitations like result limits, OCR inaccuracies, or performance constraints. It adds context beyond the schema but leaves some gaps about operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with the primary purpose, then gives a workflow usage section, and finally the Args. It is concise with minimal fluff, though the workflow section could be slightly more compact, but overall it is easy to digest.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (the prompt mentions 'Has output schema: true'), so return values are handled. The description covers the primary use case, workflow integration, and parameter examples. It does not mention edge cases like empty results or multi-page handling, but for a search tool with clear schema and workflow, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameter meaning. It explains 'package_id' with an example ('dark-37858') and clarifies that 'query' is the search term. This adds value, but since both parameters are self-evident from names and are well-described, the description does not need to over-explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Search inside a specific newspaper issue'), the resource (issue), and the output (all occurrences with exact text lines and coordinates for highlighting). It also explicitly names the sibling 'search_newspapers' and differentiates itself as a stage 2 follow-up, making it clear what this tool does that others don't.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Use this tool as Stage 2 after 'search_newspapers' whenever a snippet is cut off or you need the complete surrounding sentence') and provides concrete example use cases (uncovering full names, occupations, etc.), which helps the agent decide when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search digitized Swedish historical newspapers (17th century to circa 1908–1910).
Performs OCR full-text search and returns page-level hits with highlighted snippets and image links.
Historical Search & OCR Strategies:
- Fraktur / Gothic Print: 17th to late 19th-century newspapers were mostly printed in Fraktur/blackletter.
OCR engines frequently confuse similar glyphs (e.g. long 's' [ſ] misread as 'f', 'S', or 'l'; 'c' for 'e'; 'rn' for 'm').
- Historical Spelling & Wildcards: Use wildcard '*' or Boolean 'OR' to catch spelling variations
(e.g. 'Carlscrona OR Karlskrona', 'Gustaf OR Gustav', 'Linné OR Linnaeus', or stem wildcards like 'Söder*').
- Two-Stage Workflow:
1. Use this tool ('search_newspapers') for initial discovery of dates, issues, and page numbers.
2. If snippets are cut off or you need surrounding sentences (e.g. destinations, causes of death, full names),
call 'search_in_issue(package_id=..., query=...)' on the matched issue to retrieve complete verbatim quotes.
3. Always present the 'images.preview_width' link so users can visually verify the scanned page if OCR is unclear.
Args:
query: Search term or phrase in Swedish/English (e.g. 'ångfartyg', 'Carl von Linné', 'brand i Karlskrona').
from_date: Start date in 'YYYY-MM-DD' format or simply year 'YYYY' (e.g. '1850').
to_date: End date in 'YYYY-MM-DD' format or simply year 'YYYY' (e.g. '1899').
newspaper: Filter by specific newspaper title (e.g. 'Aftonbladet', 'Dagens Nyheter', 'Post- och inrikes tidningar', 'Göteborgsposten').
sort_by: Sort order: 'relevance' (most relevant), 'date_asc' (oldest first), or 'date_desc' (newest first).
limit: Number of results to return per page (1-100, default 20).
offset: Zero-based starting index for pagination (default 0).
max_snippets: Maximum number of text snippets to include per newspaper page (default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| sort_by | No | relevance | |
| to_date | No | ||
| from_date | No | ||
| newspaper | No | ||
| max_snippets | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It transparently discloses the tool's limitations (OCR errors in Fraktur text, possibly cut-off snippets) and prescribes mitigations (present image links, use search_in_issue for verification). It does not mention rate limits or auth, but the OCR caveat and workflow guidance provide meaningful behavioral context beyond what the schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but earns its length: the OCR background and examples are essential for effective use of this historical search tool on a difficult domain. The structure is logical (purpose → strategy → workflow → args). It could be slightly trimmed, but the density of actionable information is high and there's no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with this complexity (OCR issues, historical spelling, date handling, pagination), the description is thorough. It explains return values implicitly (page-level hits with snippets and image links), gives remediation steps when OCR is unclear, and covers all parameters. The presence of an output schema reduces the need for describing returns, and the description covers the remaining operational context well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains each parameter with concrete examples (query: 'ångfartyg', 'brand i Karlskrona'; from_date/to_date: 'YYYY-MM-DD' or 'YYYY'; newspaper: 'Aftonbladet'; sort_by options and limit/offset/max_snippets semantics). It adds value by explaining the date formats and giving example values, which the JSON schema alone does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching digitized Swedish historical newspapers with OCR full-text search, returning page-level hits with snippets and image links. It distinguishes itself from siblings by explicitly naming search_in_issue as the follow-up tool for complete verbatim quotes, making its role in the workflow clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance, including the two-stage workflow (use this tool for initial discovery, then search_in_issue for full quotes). It also advises on OCR-specific strategies like using wildcards and Boolean OR for spelling variations, which is essential for an agent to know when to use this tool effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_newspaper_page_imageget_newspaper_timelinelookup_newspaper_idsearch_in_issuesearch_newspapersScored across 5 tools
Each tool targets a separate step in the newspaper research workflow: corpus search, temporal/title aggregation, issue-level search, page image retrieval, and ID resolution. Although search_newspapers and search_in_issue both search, their scope is explicitly distinct, and the two-stage workflow clarifies when each should be used.
All tool names use snake_case and mostly follow a clear verb + newspaper-related object pattern, such as search_newspapers, get_newspaper_timeline, and get_newspaper_page_image. The prepositional form search_in_issue and the use of lookup in lookup_newspaper_id are minor deviations, but they remain predictable and readable.
Five tools form a tight, well-scoped set for a read-only historical newspaper search and display service. Each tool addresses a necessary part of the workflow without unnecessary duplication.
The set covers the core research loop: search, aggregate over time/title, drill into an issue, retrieve page images, and resolve identifiers. It lacks an explicit issue or page metadata browsing tool, but the search-first workflow makes this a minor gap rather than a dead end.
Give AI assistants access to real-time data. Search the web, compare flights, find hotels, and more.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
