# PoetryDB MCP > PoetryDB connects your AI agent to a massive public domain poetry database. It lets you search thousands of classic poems by author name, title, line count, or specific keywords within the lines. Need inspiration? Run `get_random_poems`. Building an NLP model that needs rich text data? Use `advanced_search` to combine multiple criteria like John Keats's sonnets with a line count filter. ## Overview - **Category:** databases - **Price:** Free - **Tags:** poetry, literature, public-domain, search-engine, literary-analysis ## Description **PoetryDB MCP Server** connects your AI client directly to a massive collection of public domain poetry. You're talking about thousands of classic works here, and this server lets your agent act like a digital literary researcher—it pulls precise data when you tell it what to look for. *** **list_authors** gives you a complete manifest of every single poet in the PoetryDB collection; you'll get an exhaustive list so you never have to guess who’s represented. **list_titles** handles the same thing for poems, retrieving a comprehensive list of every poetic work stored in the database. If you know who wrote it or what the poem's title is, you can target your search immediately. You run **search_by_author** to find works by a specific poet; this function supports both partial and exact name matches, so even if you only remember part of their name, you’ll get results. Similarly, you use **search_by_title** when you need poems based on the title—it finds matching works whether you give it the full name or just a snippet. For narrowing down your search, PoetryDB gives you several filters. If you're looking for sonnets, for instance, you run **search_by_linecount**, and it filters the entire database to show only those poems that contain an exact number of lines, like 14. You can also pinpoint works using **search_by_lines** when all you remember is a few key phrases or blocks of text from inside the poem's actual lines—it searches the content itself. When simple searches aren't enough, **advanced_search** lets your agent run complex queries by combining multiple criteria simultaneously. You don't have to do three separate calls; you can filter results across author, title, line count, and keywords all in one go. This is how you combine those specialized filters for the deepest research. Need inspiration fast? Don’t waste time scrolling through indexes. Just run **get_random_poems**, and it pulls an unpredictable set of random poems instantly, giving you a quick read or a starting point when you're stuck. This server gives your agent granular control over the entire database, letting you check for authors and titles, narrow by length, search content, and combine everything into one powerful call. ## Tools ### advanced_search Runs a complex query combining multiple fields like author, title, or line count simultaneously. ### list_authors Provides a complete list of every author available in the PoetryDB collection. ### get_random_poems Retrieves an unpredictable set of random poems for quick reading and inspiration. ### search_by_author Searches for poems by a specified author, supporting both partial and exact name matches. ### search_by_linecount Filters the database to find only those poems that contain an exact number of lines. ### search_by_lines Searches for poems where specific text or keywords appear within their actual poem lines. ### search_by_title Finds poems using a specified title, supporting both partial and exact matches. ### list_titles Retrieves an exhaustive list of poem titles stored in the database. ## Prompt Examples **Prompt:** ``` List all authors available in the PoetryDB. ``` **Response:** ``` I've retrieved the list of authors. There are hundreds of poets available, including classics like William Shakespeare, Emily Dickinson, and Edgar Allan Poe. Would you like to see poems from a specific author? ``` **Prompt:** ``` Find 3 random poems for me. ``` **Response:** ``` Here are 3 random selections from the database: 'Ozymandias' by Percy Bysshe Shelley, 'The Raven' by Edgar Allan Poe, and 'A Bird, came down the Walk' by Emily Dickinson. Shall I provide the full text for any of these? ``` **Prompt:** ``` Search for poems by John Keats that have exactly 14 lines. ``` **Response:** ``` Searching for sonnets by John Keats... I found several matches, including 'On First Looking into Chapman's Homer' and 'When I have fears that I may cease to be'. Both are 14-line sonnets. Which one would you like to read? ``` ## Capabilities ### List all available authors Retrieves a complete manifest of every poet in the database. ### List all poem titles Provides an exhaustive list of every poetic work stored in PoetryDB. ### Find poems by author name Searches for works, supporting both partial and exact matches against a specific poet's name. ### Search by poem title Locates poems using either the full or a partial match of the work’s official title. ### Filter poems by line count Narrows results to only include poems that have an exact number of lines you specify (e.g., sonnets with 14 lines). ### Search for specific phrases Finds poems containing a given block of text or keyword within their actual lines. ### Combine multiple search criteria Runs complex queries by simultaneously filtering results across author, title, line count, and more fields. ## Use Cases ### Analyzing Shakespearean influence. A student needs to compare sonnets that share themes but aren't by the same author. They run `list_authors` to find all known poets, then use `advanced_search` combining 'sonnet' (title filter) and a specific line count (14 lines). The agent returns a curated list for immediate comparison. ### Finding an obscure poem. A writer remembers only a few phrases from a poem but can't recall the title or author. They run `search_by_lines` with those key phrases. The agent returns matches, allowing them to retrieve the full text and finally identify the correct source. ### Building a poetry API endpoint. A developer needs thousands of clean, structured poems for an app test. Instead of manual data scraping, they call `list_authors` first, then loop through them using `search_by_author` to pull specific datasets into their application. ### Just needing a break from research. A researcher is deep in source material and needs a palate cleanser. They run `get_random_poems`. The agent pulls three unrelated poems, offering quick context shifts and fresh reading without any search parameters. ## Benefits - Stop manually checking external websites for poem existence. `list_titles` and `list_authors` give you a single, definitive manifest of every piece in the collection. - Get immediate creative hits without effort. Just run `get_random_poems` to pull three completely different poems from authors you might never have heard of. - Don't just search by author; combine criteria. The `advanced_search` tool lets you filter for 'sonnets by Keats with 14 lines' in one go, which is impossible otherwise. - Pinpoint text fragments fast. If you only remember a specific line—like 'the stars shine bright tonight'—use `search_by_lines`. You don’t need the author or title to start your research. - Perfect for academic work: Use `search_by_linecount` when analyzing formal poetry, guaranteeing that every result meets strict structural criteria (e.g., filtering only 12-line poems). - It's a single source of truth. Instead of juggling multiple databases or archives, all the data is exposed through simple API calls. ## How It Works The bottom line is: your AI client acts as a digital scholar, running complex queries across thousands of poems without you having to write SQL or use an external website. 1. First, subscribe to the PoetryDB server on Vinkius. Then, your AI client uses an access identifier (use 'PUBLIC' for standard read access) to connect. 2. Next, you ask your agent a specific question—for example: 'Find me poems by Emily Dickinson that have 14 lines and mention 'chance'.' The agent maps this request to the right tool. 3. Finally, the PoetryDB server executes the query against the database and sends back the structured list of matching poem data. ## Frequently Asked Questions **How do I find a poem if I only know a few words? (Using search_by_lines)** Use `search_by_lines`. You feed your agent the specific text snippet you remember. The server searches all lines in the database and returns any poems that contain those keywords, regardless of author or title. **What if I want to check how many authors are available? (Using list_authors)** Just run `list_authors`. This tool fetches a complete manifest of every single poet stored in PoetryDB. It's the fastest way to see who you can search for. **Can I combine multiple filters like author and line count? (Using advanced_search)** Yes, that’s exactly what `advanced_search` is for. You pass all criteria—like 'Jane Austen' AND '12 lines'—and it returns only the perfect matches. **Is there a way to just get something random? (Using get_random_poems)** Use `get_random_poems`. This tool bypasses all searching and simply pulls three random selections from the database. It’s great for quick inspiration. **How do I see the full catalog of available poem titles using list_titles?** The `list_titles` tool returns every title currently indexed in PoetryDB. This lets you quickly map out your research scope before running specific content searches. **What happens if I run search_by_linecount with an impossible number?** The server rejects the query and returns a clear error message indicating invalid input parameters. You must use positive integers for line counts to successfully retrieve poems. **Does search_by_author support partial name matches or does the author need to be exact?** The `search_by_author` tool handles both partial and exact matches. This flexibility means you can use fragments of a poet's name if you aren't sure of the correct spelling. **What access identifier do I input when setting up my AI agent connection?** You should enter 'PUBLIC'. Using this standard identifier allows your AI client to connect and explore the literature collection without needing a custom API key or complex authentication setup. **Can I search for poems that contain specific words or phrases in their text?** Yes! Use the `search_by_lines` tool. Provide a string, and the agent will return poems that include that specific text within their lines. **Is it possible to find a poem if I only know the author and the approximate length?** Absolutely. You can use the `advanced_search` tool to combine fields like 'author' and 'linecount' to narrow down the results to exactly what you're looking for. **How can I discover new poets I haven't read before?** You can use `list_authors` to see the full directory of available poets, or use `get_random_poems` to have the agent surprise you with a random selection from the database.