Perseus MCP: End-User Guide

Use Perseus MCP with Cursor, Claude Desktop, ChatGPT, or another MCP-capable client to discover, search, retrieve, and navigate Greek and Latin texts from Perseus CTS and Scaife.

The server does not require a Perseus, Scaife, or OpenRouter API key. Cursor, Claude Desktop, and similar clients can run it locally. ChatGPT instead needs an HTTPS-accessible MCP endpoint.

Quick start

You need:

• Python 3.11 or newer;
• uv (recommended);
• an MCP-capable client.

From the project directory:

uv sync
uv run perseus-mcp

If the second command starts without an error, the server is ready. Stop it with Ctrl+C, then add it to your MCP client using the configuration below.

Prefer pip?

pip install -e .
perseus-mcp

Connect your MCP client

For a local MCP client, the application launches this command:

uv --directory /full/path/to/Perseus-mcp run perseus-mcp

Replace /full/path/to/Perseus-mcp with the absolute path to this repository.

{
  "mcpServers": {
    "perseus": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/Perseus-mcp",
        "run",
        "perseus-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "perseus": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/Perseus-mcp",
        "run",
        "perseus-mcp"
      ]
    }
  }
}

where uv

which uv

rg "sk-or-v1-[A-Za-z0-9_-]{20,}" examples/*.ipynb

Verify the connection

After restarting a local client, or adding the connector to a ChatGPT conversation:

1. Confirm that the perseus MCP server is connected.
2. Ask the client to list its Perseus tools.

3. Try:

   Use the Perseus tools to find Homer and list his available works.

You should see calls to tools such as find_author_names, get_author_resources, or list_text_groups.

You can also test the server independently with MCP Inspector:

npx @modelcontextprotocol/inspector uv run perseus-mcp

A reliable research workflow

Ask the model to work in four stages:

1. Discover an author, work, or CTS URN.
2. Select the appropriate work or edition.
3. Retrieve or navigate passages.
4. Verify important results against raw CTS XML.

Example prompt:

Use the Perseus tools to find Homer’s Iliad. Select a Greek CTS edition, retrieve Iliad 1.1–1.7 as plain text, and then show the raw CTS response used to verify it.

Useful tools at each stage:

Discover authors, works, and URNs

Start with discovery instead of guessing CTS URNs.

Examples:

find_author_names("Hom", language="greek")
list_text_groups(language="latin", query="Ovid")
get_author_resources("Homer", language="greek")
get_work_resources("Iliad")

Typical CTS URNs:

Perseus CTS and Scaife may expose different editions of the same work. Use get_author_resources or get_work_resources to discover a CTS edition before requesting a CTS passage.

Retrieve and navigate passages

For readable text:

get_passage_plaintext(
  "urn:cts:greekLit:tlg0012.tlg001.perseus-grc1:1.1"
)

For the original CTS response:

get_passage(
  "urn:cts:greekLit:tlg0012.tlg001.perseus-grc1:1.1"
)

For neighboring citations:

get_prev_next_urn(
  "urn:cts:greekLit:tlg0012.tlg001.perseus-grc1:1.1"
)

If Perseus returns malformed HTML for a navigation operation, the server can derive a well-formed result from the valid-reference inventory.

Search Greek and Latin text

search_perseus searches the Scaife library:

search_perseus("μῆνιν", language="greek")

Greek can also be entered as Beta Code:

search_perseus("mh=nin", language="greek", query_format="betacode")

Useful options:

• search_kind="lemma" searches lemmas instead of surface forms;
• author="Homer" scopes by a resolved author;
• text_group=... or work=... scopes directly by URN;
• page_num=2 requests another results page;
• result_format="passages" groups results by passage;
• preserve_operators=True preserves quotes and operators such as -, |, *, and ~.

For ambiguous ASCII input, set query_format="betacode" to convert it or query_format="unicode" to preserve it.

Tool groups

The server currently provides 23 text-returning tools.

Passage and navigation

• get_passage
• get_passage_plus
• get_passage_plaintext
• get_valid_references
• get_valid_references_json
• count_valid_references
• get_label
• get_first_urn
• get_prev_next_urn

Discovery

• get_capabilities
• list_text_groups
• find_author_names
• get_author_resources
• get_work_resources

Search

• search_perseus
• search_within_text
• get_passage_highlights

Scaife retrieval

• get_scaife_library_metadata
• get_scaife_passage_json
• get_scaife_passage_text

Cache management

• get_cache_status
• refresh_metadata_cache
• clear_metadata_cache

Raw CTS tools return XML text. Search tools return Scaife JSON text. Discovery tools return locally shaped JSON text. get_passage_plaintext returns readable text.

Metadata cache

The server caches stable CTS capabilities, valid references, and Scaife library metadata to reduce repeat requests.

By default, the cache is stored at .cache/perseus-mcp relative to the process’s working directory. Use one absolute PERSEUS_MCP_CACHE_DIR if an MCP client and notebook should share the same disk cache.

On Windows, OneDrive can temporarily lock or mark cache directories read-only. Close the process holding the directory and retry clear_metadata_cache().

Troubleshooting

Claude Desktop logs:

• Windows: %APPDATA%\Claude\logs
• macOS: ~/Library/Logs/Claude

Next steps

• Browse the example notebooks for guided workflows.
• See the architecture guide for implementation details.
• Report reproducible problems through the GitHub issue tracker.