libapps-mcp
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., "@libapps-mcp find the psychology research guide and summarize its main page"
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.
libapps-mcp
Read-only MCP server for LibGuides sites, built on the Springshare LibApps API v1.2. It lets an AI assistant browse published research guides (including every page and sub-page as clean markdown), guide subjects, the A-Z database list, and public subject-librarian profiles. Runs over stdio.
Nothing institution-specific is built in: the API region host, public site URL,
and credentials are all configuration. Without credentials the server still
starts, and every tool returns config_missing.
What this does not do
Write anything (no create/update tools; the app needs GET scopes only)
Show unpublished guides, Internal or Template guides, or draft content
Index content or keep its own search index
Other Springshare products (LibCal, LibAnswers, LibWizard)
Hosted / remote access (see Phase 2)
Related MCP server: superFetch MCP Server
Requirements
A LibGuides CMS site
A read-only LibApps v1.2 application with GET scopes for Guides, Subjects, A-Z, Accounts, and Assets
uv and Python 3.11+
Credentials
In LibApps, go to Tools > API > Applications and create (or reuse) an
application with only the GET scopes above. That page also shows your
region's API host (for example lgapi-us.libapps.com); use it for
LIBAPPS_API_BASE.
Keep the client secret out of git, tickets, and chat. Put it in your MCP host
config or a local, git-ignored env file. .env.example lists the variables
with placeholder values. Rotate the secret if it is ever exposed.
Install
cd /path/to/libapps-mcp
uv sync --extra devClaude / MCP host config
Point Claude Desktop (or another stdio MCP host) at the checkout with
uv run --directory. Replace /path/to/libapps-mcp with your clone path
and the placeholder values with your own:
{
"mcpServers": {
"libapps": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/libapps-mcp",
"python",
"-m",
"libapps_mcp"
],
"env": {
"LIBAPPS_API_BASE": "https://lgapi-us.libapps.com",
"LIBAPPS_CLIENT_ID": "your-client-id",
"LIBAPPS_CLIENT_SECRET": "your-client-secret",
"LIBGUIDES_SITE_URL": "https://guides.lib.uchicago.edu"
}
}
}
}You can also run the console script uv run libapps-mcp from a shell for a
quick smoke check.
Configuration
All settings are environment variables. They are read at the first tool call.
Variable | Default | Purpose |
| (required) | OAuth client credentials for the v1.2 app |
|
| Region host: |
| derived from guide URLs | Public site origin, used for page fetches |
| (none) | Extra comma-separated hosts the page fetcher may use |
|
| Read page content from public guide pages. |
|
| Include Private guides and hidden pages/boxes |
|
| Include the public-profile contact email for librarians |
|
| Cache lifetimes (seconds) for the guide list; subjects, accounts, and A-Z; and guide outlines, pages, and searches |
|
| HTTP timeout (seconds) |
|
| Maximum concurrent upstream requests |
|
| Default markdown budget per |
|
| User agent for all requests |
|
| Log level; logs go to stderr only |
Tools
Every tool returns {"ok": true, ...} or
{"ok": false, "error": "...", "code": "..."}. Codes: config_missing,
config_invalid, auth_failed, scope_missing, not_found, not_public,
upstream_error, rate_limited, fetch_blocked, invalid_input. List tools
take limit (max 50) and offset and return total and next_offset
(null when done).
Reading guides: get_guide then get_guide_content
search_guidesfinds a guide.get_guide(guide_id)returns its metadata and the page tree: every visible page and sub-page withpage_id,name,url, and box names.get_guide_content(guide_id, page_id, include_subpages)returns that page as markdown, one entry per content box in display order. Withinclude_subpages=trueit adds the page's sub-pages. Each response also includes the fulloutline, so the assistant can move to any other page.
search_guides
Argument | Notes |
| Uses the site's relevance-ranked guide search ( |
| Subject name (substring) or id |
| Owner name; only owners with a public profile can match |
|
|
| Default 10 / 0 |
Returns id, name, url, description, type, subjects, updated,
rank, and owner (name and profile link) when the owner has a public profile.
get_guide
Argument | Notes |
| Numeric guide id |
Pages have page_id, name, url, parent_id, box_count, boxes
(box_id, name, column, position), and subpages. Link pages carry
redirect_url and are never followed.
get_guide_content
Argument | Notes |
| Numeric guide id |
| Defaults to the guide's first page |
| Add the page's sub-pages (default |
|
|
| Markdown budget (default |
| Box index to resume from (use |
Boxes that are in the outline but not on the page are marked missing. A box
cut to fit the budget is marked truncated. Embedded widgets become
[embedded: ...] placeholders.
list_subjects
with_published_guides (default true) limits the list to subjects that have
published guides. Returns id, name, slug, and parent_id.
search_databases
Argument | Notes |
| Matches name, alternate names, vendor, and description |
| Name (substring) or id |
| Default 20 / 0 |
Returns id, name, url, proxied, vendor, a short description,
subjects, types, and alt_names / new / trial / popular when available.
get_database
database_id: the same fields with the full description and more_info.
find_subject_librarians
subject: name or id. Returns librarians with a public profile for that
subject: name, title, pronouns, profile_url, image_url, subjects,
and the contact details (phone, address, website) they chose to show
publicly.
Privacy and safety
Published only. Unpublished, Internal, and Template guides are never returned. Private guides and hidden pages/boxes need
LIBAPPS_INCLUDE_PRIVATE=1.Allowlisted output. Every result is built field by field. Login emails, account ids, widget code, and A-Z internal notes and reviews are never returned. Librarians without a public profile are excluded. Contact details appear only when the profile shows them, and the profile email only with
LIBAPPS_EXPOSE_EMAIL=1.No email addresses by default. Unless
LIBAPPS_EXPOSE_EMAIL=1, email addresses in page text and descriptions are replaced with[email removed].Secrets stay private. The client secret and access token are never logged or returned; settings
repr()hides the credentials.Safe page fetches. Only
httpsURLs from API data, on the site host orLIBGUIDES_ALLOWED_HOSTS. Redirects are re-checked (max 3), pages are capped at 2 MB and must betext/html, and no cookies or auth headers are sent.Polite client. Cached responses, a concurrency cap,
gzip, and backoff on 429/5xx.
Development
uv run pytestUnit tests mock all HTTP with synthetic fixtures. An opt-in live smoke test reads credentials from the environment and asserts only on shapes and counts:
LIBAPPS_LIVE_TESTS=1 uv run pytest -m liveNotes on the API behaviors this server relies on are in
docs/api-notes.md.
To verify a running server end to end against the live API (stdio startup,
every tool, privacy and status filters, error shapes), follow
.claude/skills/verify-libapps-mcp/SKILL.md.
Its driver reads credentials from ~/.config/libapps-mcp/env. If only
~/.config/uc-libapps-mcp/env exists (the path used before this project was
renamed from uc-libapps-mcp), it reads that instead.
Phase 2: hosted (later)
A later phase adds a streamable HTTP transport served at /mcp behind TLS and
an authenticating proxy, with per-deployment LibApps credentials kept
server-side.
License
MIT
Available Tools
7 toolsfind_subject_librariansARead-only
Find librarians with a public profile for a subject (name or id). Returns names, titles, profile links, and contact details they chose to show publicly.
Inputs: subject (required). Returns: object
get_databaseARead-only
Get one A-Z database by id, with its full description and access URL.
Inputs: database_id (required). Returns: object
get_guideARead-only
Get a guide's metadata and its full page outline: a tree of pages and sub-pages with page_id, name, url, and box names. Use get_guide_content with a page_id to read a page.
Inputs: guide_id (required). Returns: object
get_guide_contentARead-only
Read a guide page as markdown, one entry per content box in display order. Defaults to the guide's first page; pass page_id (from get_guide or the returned outline) for another page, and include_subpages=true to add its sub-pages. source: auto (default), html (public page), or api (unplaced text blocks for the whole guide). Output is capped at max_chars; continue with offset=next_offset.
Inputs: guide_id (required), offset, source, page_id, +2 more. Returns: object
list_subjectsARead-only
List the site's guide subjects (id, name, slug). By default only subjects that have published guides.
Inputs: with_published_guides. Returns: object
search_databasesARead-only
Search the A-Z database list by name, alternate names, vendor, and description. Optional filters: subject and az_type (name or id). Without a query, lists databases alphabetically. Paginate with limit (max 50) and offset.
Inputs: limit, query, offset, az_type, +1 more. Returns: object
search_guidesARead-only
Search published research guides. With a query, uses the site's relevance-ranked full-text guide search (source 'server'); without one, or if that search fails, matches guide names, subjects, descriptions, and owner names locally (source 'local'). Optional filters: subject (name or id), owner (public profile name), guide_type (e.g. subject, course, topic, general, or type id). Paginate with limit (max 50) and offset; next_offset is null when done.
Inputs: limit, owner, query, offset, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools target clearly distinct resources and actions, with search_guides (find), get_guide (metadata+outline), and get_guide_content (page text) forming a coherent retrieval pipeline. The get_guide vs get_guide_content pair is the only mild overlap, but descriptions clearly delineate their roles.
All seven tools follow a consistent verb_noun pattern (list_subjects, search_guides, get_guide, get_guide_content, search_databases, get_database, find_subject_librarians). Verb variety (list/search/get/find) reflects genuinely different operations rather than inconsistency.
Seven tools is well-scoped for an A-Z database and research guide server, with each tool earning its place across the subjects, guides, databases, and librarians domains. No redundant or trivial tools.
The surface covers the core read workflows: subjects, guide discovery and content, databases, and subject librarians, with pagination handled throughout. As a read-only surface it lacks write operations and some minor browse helpers (e.g., listing guide types), but core research workflows are covered.
Related MCP Connectors
Read any public web page as clean Markdown for LLMs. Respects robots.txt. Free tier; x402 paid API.
Read authorized public pages as Markdown or HTML metadata. Operated by an autonomous AI agent.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Read any web page as clean Markdown for AI agents: fetch, search, metadata, links. SSRF-safe.
Related MCP Servers
- AlicenseAqualityBmaintenanceThis server enables LLMs to retrieve and process content from web pages, converting HTML to markdown for easier consumption.101225,076 PyPI91,952MIT
- AlicenseAqualityDmaintenanceAn MCP server that fetches web pages and extracts clean, AI-friendly Markdown content using Mozilla Readability. It provides secure web access for LLMs with built-in SSRF protection and automated content cleaning for improved context retrieval and summarization.180 npmMIT
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for browsing, searching, and exporting a Zotero library from AI assistants.-
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that fetches URLs and returns clean, readable markdown, enabling AI assistants to read any webpage with article extraction, caching, and security features.3MIT