ra-mcp

A Model Context Protocol server and CLI for searching and browsing transcribed historical documents from the Swedish National Archives (Riksarkivet). Provides full-text search across millions of AI-transcribed pages, complete page transcriptions, high-resolution IIIF image access, and archival research guides — all as MCP tools that any LLM client can use.

Quick Start (MCP)

Streamable HTTP — works with ChatGPT, Claude, and any MCP-compatible client:

https://riksarkivet-ra-mcp.hf.space/mcp

Claude Code:

claude mcp add --transport http ra-mcp https://riksarkivet-ra-mcp.hf.space/mcp

IDE (mcp.json):

{
  "mcpServers": {
    "ra-mcp": {
      "type": "streamable-http",
      "url": "https://riksarkivet-ra-mcp.hf.space/mcp"
    }
  }
}

Quick Start (CLI)

uv pip install ra-mcp

# Search transcribed documents
ra search "trolldom"
ra search "((Stockholm OR Göteborg) AND troll*)"

# Browse specific pages
ra browse "SE/RA/310187/1" --pages "7,8,52" --search-term "trolldom"

See packages/search-cli and packages/browse-cli for full syntax and search operators.

Architecture

The project is a uv workspace with eight modular packages plus a root server:

Package	Purpose	README
ra-mcp (root)	Server composition and Typer CLI entry point	—
ra-mcp-common	Shared HTTP client, telemetry helpers	README
ra-mcp-search	Search domain: models, API client, operations	README
ra-mcp-browse	Browse domain: models, ALTO/IIIF/OAI-PMH clients	README
ra-mcp-search-mcp	MCP tools: search_transcribed, search_metadata	README
ra-mcp-browse-mcp	MCP tool: browse_document	README
ra-mcp-search-cli	CLI command: ra search	README
ra-mcp-browse-cli	CLI command: ra browse	README
ra-mcp-guide-mcp	MCP resources: archival research guides	README

ra-mcp-common              (no internal deps)
       ↑
ra-mcp-search              (depends on common)
ra-mcp-browse              (depends on common)
       ↑
ra-mcp-search-mcp          (depends on search + fastmcp)
ra-mcp-browse-mcp          (depends on browse + fastmcp)
ra-mcp-guide-mcp           (depends on common + fastmcp)
ra-mcp-search-cli          (depends on search + typer + rich)
ra-mcp-browse-cli          (depends on browse + typer + rich)
       ↑
ra-mcp (root)              (composes all MCP and CLI packages)

Deployment

Docker:

docker run -p 7860:7860 riksarkivet/ra-mcp:latest

Helm:

helm install ra-mcp charts/ra-mcp \
  --set image.tag=v0.4.2-alpine \
  --set opentelemetry.enabled=true

See charts/ra-mcp/ for the full values reference (autoscaling, ingress, PDB, security contexts, etc.).

Health endpoints (available when running with HTTP transport):

Endpoint	Purpose
/health	Liveness — always returns {"status": "ok"}
/ready	Readiness — returns mounted modules or 503 if none loaded

Observability

Telemetry is gated on a single environment variable. When enabled, traces, metrics, and logs are exported via OTLP.

Variable	Default	Description
RA_MCP_OTEL_ENABLED	false	Master switch
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4317	Collector endpoint
OTEL_EXPORTER_OTLP_PROTOCOL	grpc	grpc or http/protobuf
OTEL_SERVICE_NAME	ra-mcp	Service name
RA_MCP_OTEL_LOG_BRIDGE	true	Bridge Python logging to OTel

Instrumented components: HTTP client (spans + request/error/duration/size metrics), search and browse operations, ALTO/IIIF/OAI-PMH clients, and CLI commands. FastMCP adds automatic spans for all tools/call and resources/read operations.

Development

git clone https://github.com/AI-Riksarkivet/ra-mcp.git && cd ra-mcp
uv sync

# Run code quality checks (format + lint + typecheck)
make check

# Or via Dagger (same as CI)
dagger call checks

# Start HTTP server for local development
uv run ra serve --port 8000

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run ra serve

APIs & Data Sources

API	Endpoint	Documentation
Search API	https://data.riksarkivet.se/api/records	Wiki
IIIF Collections	https://lbiiif.riksarkivet.se/collection/arkiv	Wiki
IIIF Images	https://lbiiif.riksarkivet.se	—
ALTO XML	https://sok.riksarkivet.se/dokument/alto	—
Bildvisning	https://sok.riksarkivet.se/bildvisning	—
OAI-PMH	https://oai-pmh.riksarkivet.se/OAI	Wiki

Additional resources: Riksarkivet Data Platform Wiki, Förvaltningshistorik (semantic search, experimental), HTRflow (handwritten text recognition).

License

Apache 2.0