PoetryDB MCP Server README

PoetryDB MCP Server

Unofficial MCP server for exploring classic poetry through PoetryDB.

At a glance

Install

npm install -g mcp-poetry

Or from source:

npm install
npm run build

MCP Registry

This server is published to the MCP Registry under:

io.github.lacausecrypto/poetrydb

Claude Desktop

{
  "mcpServers": {
    "poetrydb": {
      "command": "npx",
      "args": ["-y", "mcp-poetry"]
    }
  }
}

For a local checkout, replace the command with:

{
  "mcpServers": {
    "poetrydb": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-poetrydb/dist/index.js"]
    }
  }
}

Tools

Catalog

• catalog_overview: list categories and available tools
• catalog_category: show tools for a specific category

Search

• search_by_author: find poems by author name
• search_by_title: find a poem by title
• search_by_lines: search text inside poem lines
• search_by_linecount: find poems by exact line count
• search_combined: query multiple PoetryDB fields in one request
• list_authors: list all available authors

Discovery

• random_poem: fetch one or more random poems
• get_sonnets: fetch 14-line poems
• get_haikus: fetch 3-line poems
• list_titles: list poem titles

Example requests

Simple

Random poem please.

Expected tool:

random_poem({ "count": 1 })

Browse

Show me the available poets.

Expected tool:

list_authors({})

Targeted search

Find Ozymandias.

Expected tool:

search_by_title({ "title": "Ozymandias" })

Text search

Show me poems containing the word "love".

Expected tool:

search_by_lines({ "text": "love" })

Form-based discovery

Give me 14-line poems by Shakespeare.

Expected tool:

search_combined({ "fields": "author,linecount", "values": "Shakespeare;14" })

More advanced

List Shakespeare results, but only return title and linecount.

Expected tool:

search_by_author({ "author": "Shakespeare", "fields": "title,linecount" })

Multi-step exploration

Start with the catalog, then show me the discovery tools, then give me a sonnet.

Typical tool sequence:

catalog_overview({})
catalog_category({ "category_id": "discovery" })
get_sonnets({})

Development

npm run build
npm run test:ci
npm test
npm pack --dry-run

Environment variables:

• POETRYDB_BASE_URL
• POETRYDB_REQUEST_TIMEOUT_MS
• POETRYDB_REQUEST_RETRIES

Notes

• No API key is required.
• This package is not affiliated with PoetryDB.
• Built for MCP clients that prefer a compact stdio server over a custom PoetryDB integration.
• MCP Registry identity: io.github.lacausecrypto/poetrydb

Attribution

• PoetryDB: poetrydb.org
• Upstream project: thundercomb/poetrydb

Additional implementation notes are in documentation.md.