clear_metadata_cache
Clear local metadata cache files and in-memory cache entries.
LABSCO SUMMARY
The URN you guess is often not the URN Perseus has.
Edition identifiers differ between Perseus CTS and Scaife search results, and the live inventory changes, so the discovery tools are not decoration — resolve the author and work first, then build the passage URN from what came back. Heavy request loops draw a 429 from Perseus, which the server surfaces rather than silently retrying.
What it is
A local server over the Perseus Digital Library and the Scaife API. It fetches passages by CTS URN as raw CTS XML or plain readable text, walks a work's citation references, and searches Greek and Latin texts in Unicode or Beta Code.
What you get
- Passages — get_passage, get_passage_plus for surrounding metadata, get_passage_plaintext for readable text
- Navigation — get_valid_references, get_valid_references_json, count_valid_references, get_first_urn, get_prev_next_urn, get_label
- Discovery — get_capabilities, list_text_groups, find_author_names, get_author_resources, get_work_resources
- Search — search_perseus across the corpus, search_within_text inside one edition, get_passage_highlights for token positions in a passage
- Scaife JSON — get_scaife_library_metadata, get_scaife_passage_json, get_scaife_passage_text
- Cache control — get_cache_status, refresh_metadata_cache, clear_metadata_cache
- Greek queries accept Unicode or Beta Code, and search by inflected form or by dictionary lemma
Requirements
Python 3.11 or later and uv. Clone the repository, run uv sync in it, and have your client launch uv --directory with the clone's full path to run perseus-mcp over stdio — the configuration the project publishes. No account, no key. Discovery and navigation results cache to disk under .cache/perseus-mcp in the working directory — PERSEUS_MCP_CACHE_DIR points that at an absolute path so notebooks and MCP clients share one cache, PERSEUS_MCP_CACHE_TTL_SECONDS changes the default of 86400 seconds, and PERSEUS_MCP_DISABLE_CACHE=1 turns it off.
Setup effort
Build from source — git clone https://github.com/tonyjurg/Perseus-mcp.git
USE CASES
01
Pulling one passage of Homer or Virgil
Fetch it by CTS URN, as readable text rather than the raw XML.
02
Finding which editions of a work actually exist
Match a partial author name, then list that author's works, editions and translations before constructing a URN.
03
Searching Greek by form or by lemma
Query in Unicode Greek or Beta Code, scoped to an author, a text group or a single edition.
04
Reading a work straight through
Start at the first reference and step forward passage by passage, or page the citation list as JSON.
05
Avoiding repeated multi-megabyte metadata fetches
Inspect the local cache, refresh it deliberately, or clear it when the upstream inventory changes.
23 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
count_valid_references
Count valid citation references without returning the full reference list.
find_author_names
Find author/textgroup names by partial name match across Perseus catalogs.
This merges the legacy CTS capabilities inventory with Scaife's library catalog, then matches author/textgroup name fields only, not work titles. A result can therefore be found when either upstream inventory contains it. limit must be between 1 and 500. Use offset with has_more to page through all matching authors. Examples:
- query: "Hom"
- query: "Plut"
get_author_resources
List CTS works/editions/translations for an author name or textgroup URN.
Examples:
- author: "Homer"
- author: "tlg0012"
- author: "urn:cts:greekLit:tlg0012"
get_cache_status
Get local metadata cache status.
get_capabilities
Get the list of available texts and editions from Perseus CTS.
get_first_urn
Get the first available reference URN for a work/edition URN.
get_label
Get human-readable labels/metadata for a CTS URN (work or edition).
get_passage
Get the text of a specific passage using a CTS URN.
Examples:
- urn:cts:greekLit:tlg0012.tlg001:1.1-1.10
- urn:cts:greekLit:tlg0012.tlg001.perseus-grc1:1.1
get_passage_highlights
Get Scaife token highlight positions for a query within one passage.
get_passage_plaintext
Get a passage as plain readable text instead of raw CTS XML.
get_passage_plus
Get passage text plus surrounding metadata/context for a CTS URN.
get_prev_next_urn
Get previous and next URNs for a passage URN.
get_scaife_library_metadata
Get Scaife JSON metadata for a textgroup, work, edition, or translation URN.
get_scaife_passage_json
Get Scaife JSON passage metadata/content for a passage URN.
get_scaife_passage_text
Get Scaife plaintext for a passage URN.
get_valid_references
Get valid citations/references for a work, useful for navigation.
Optionally pass a citation level to constrain returned references.
get_valid_references_json
Get valid citation references as paged JSON instead of raw CTS XML.
limit must be between 1 and 500.
get_work_resources
List editions/translations/resources for a matching work URN or title.
Optional language accepts values such as "greek", "grc", "latin", or "lat" and filters by the original work language.
Examples:
- urn_or_title: "urn:cts:greekLit:tlg0012.tlg001"
- urn_or_title: "Iliad"
list_text_groups
List authors/textgroups and their works from CTS capabilities.
Optional language accepts values such as "greek", "grc", "latin", or "lat". Optional query matches author names, textgroup URNs, or work titles. limit must be between 1 and 500. Use offset with has_more to page through matching textgroups.
refresh_metadata_cache
Refresh cached CTS and Scaife library metadata.
search_perseus
Search Perseus texts via Scaife API.
For Greek searches, query may be Unicode Greek or Beta Code. The default query_format="auto" detects explicit Beta Code marks such as =, /, (, ), and *, and also accepts short unaccented Beta Code queries such as logos. Set query_format="betacode" to force conversion or query_format="unicode" to preserve ASCII text in Greek searches. The language value determines whether Greek query normalization is applied; it is not sent to Scaife as a corpus language filter. Optional author resolves a CTS author/textgroup name or URN, then locally filters the current Scaife result page to matching CTS URN prefixes. search_kind may be "form" or "lemma". Set preserve_operators=True for Scaife operator queries such as quoted phrases, -, |, *, or ~. Optional page_num, text_group, work, and result_format are passed to Scaife's library search endpoint. When author resolves to exactly one CTS textgroup and no explicit text_group or work is supplied, the author scope is sent to Scaife as a server-side text_group filter.
search_within_text
Search within a single Scaife text/edition URN.
size must be between 1 and 500.
BEFORE YOU INSTALL
What to know first
Tools you get
23 tools when we connected.
Requires
- uv on PATH
- Python 3.11 or later
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 23 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/tonyjurg/Perseus-mcp.git
cd Perseus-mcp
uv syncMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"perseus": {
"command": "uv",
"args": [
"--directory",
"<YOUR_PATH_TO_PERSEUS_MCP>",
"run",
"perseus-mcp"
]
}
}
}<YOUR_PATH_TO_PERSEUS_MCP> is the full path of your Perseus-mcp clone. If Claude Desktop cannot find uv, put the full path of the uv executable in "command".
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add perseus -- uv --directory <YOUR_PATH_TO_PERSEUS_MCP> run perseus-mcp<YOUR_PATH_TO_PERSEUS_MCP> is the full path of your Perseus-mcp clone.
