DraCor MCP Server
A Model Context Protocol (MCP) server for interacting with the Drama Corpora Project (DraCor) API. This MCP server enables you to seamlessly analyze dramatic texts and their character networks through Claude or other LLMs.
Overview
This project implements an MCP server using the official Model Context Protocol Python SDK that provides access to the DraCor API v1. It allows Claude and other LLMs to interact with dramatic text corpora, analyze character networks, retrieve play information, and generate insights about dramatic works across different languages and periods.
The project includes two implementations:
dracor_mcp_fastmcp.py- Streamlined implementation using the FastMCP decorator-based API with v1 API
Features
- Access to DraCor API v1 through a unified interface
- No authentication required (DraCor API is publicly accessible)
- Structured data models for DraCor entities
- Support for operations:
- Corpora and play information retrieval
- Character network analysis
- Metrics and statistics for plays
- Character information and spoken text
- Comparative play analysis
- Search functionality
- Character relationship data
- Network data in multiple formats (CSV, GEXF, GraphML)
- Gender analysis across plays
- Full text retrieval in plain text and TEI XML formats
- Complete play text analysis
Setup
Prerequisites
- Python 3.10 or higher
- UV package manager (recommended) or pip
Installation with UV
- Install UV:
pip install uv
- Create a virtual environment and install dependencies:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
- Install the MCP server in Claude Desktop:
For standard implementation (v0 API):
mcp install dracor_mcp_server.py
Or for FastMCP implementation with v1 API (recommended):
mcp install dracor_mcp_fastmcp.py
Development Mode
For testing and development:
mcp dev dracor_mcp_server.py
Or for FastMCP implementation with v1 API (recommended):
mcp dev dracor_mcp_fastmcp.py
This will launch the MCP Inspector where you can test your tools and resources interactively.
Claude Configuration
You can also directly configure Claude to use the DraCor MCP server by adding the following to your Claude configuration file:
{
"mcpServers": {
"DraCor API v1": {
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli]",
"--with",
"requests",
"--with",
"pydantic",
"--with",
"python-multipart",
"mcp",
"run",
"/path/to/dracor-mcp/dracor_mcp_fastmcp.py"
],
"env": {
"DRACOR_API_BASE_URL": "https://dracor.org/api/v1"
}
}
}
}
Replace /path/to/dracor-mcp/ with the actual path to your dracor-mcp directory. This configuration uses uv run to execute the MCP server with the necessary dependencies without requiring a prior installation.
If you want to use a different server, e.g. the staging server, change it in the environment variable DRACOR_API_BASE_UR in the configuration file:
"env": {
"DRACOR_API_BASE_URL": "https://staging.dracor.org/api/v1"
}
Docker (optional)
If you prefer using Docker:
docker build -t dracor-mcp .
docker run dracor-mcp
To use the FastMCP implementation with v1 API instead:
docker run -e IMPLEMENTATION=fastmcp dracor-mcp
Implementation Details
Standard MCP Implementation (v0 API)
The standard implementation in dracor_mcp_server.py uses the core MCP SDK classes with the older v0 API:
Resource- For defining API resourcesMCPToolImpl- For implementing toolsPromptTemplate- For creating prompt templates
FastMCP Implementation (v1 API)
The FastMCP implementation in dracor_mcp_fastmcp.py uses a more concise decorator-based approach with the current v1 API:
@mcp.resource()- For defining API resources@mcp.tool()- For implementing tools@mcp.prompt()- For creating prompt templates
This approach results in cleaner, more maintainable code while providing the same functionality but with access to more comprehensive API features.
v1 API Features
The v1 API implementation provides access to many additional endpoints and capabilities:
- API info - Version information for the DraCor API
- Corpus metadata - Detailed metadata for all plays in a corpus
- Play metrics - Network metrics and analysis data
- Character network data - CSV, GEXF, and GraphML formats
- Character relations - Explicit relationships between characters
- Spoken text filters - Filter by gender, relation type, or character role
- Stage directions - Retrieve stage directions with or without speakers
- Character lookup - Find plays containing specific characters (by Wikidata ID)
Usage
Once installed in Claude Desktop, you can interact with the DraCor API through Claude. Here are some examples:
Basic Queries
- Ask Claude to list available corpora:
Can you list all available drama corpora in DraCor?
- Get information about a specific play:
Tell me about Goethe's Faust in the German corpus
- Analyze character networks:
Analyze the character network in Hamlet from the Shakespeare corpus
Advanced Queries
- Analyze character relationships:
What are the strongest character relationships in Pushkin's Boris Godunov?
- Compare plays:
Compare Goethe's Faust and Schiller's Die Räuber in terms of network density and character count
- Analyze character importance:
Who are the most central characters in Shakespeare's Hamlet based on speaking time and relationships?
- Analyze gender representation:
Analyze the gender distribution and representation in Molière's Le Misanthrope
- Find a character across different plays:
Find all plays that feature a character named "Hamlet" or similar
- Analyze the full text of a play:
Provide a comprehensive analysis of the full text of Goethe's Faust
- Extract themes from play text:
What are the main themes and motifs in the full text of Shakespeare's Hamlet?
- Analyze language patterns:
Analyze the language patterns and style in Chekhov's The Cherry Orchard
Literary Analysis Queries
- Analyze play structure:
Analyze the structure of Molière's Le Misanthrope in terms of acts, scenes, and dialogue distribution
- Compare authors:
Compare the network structures in plays by Shakespeare and Molière
- Historical context:
Put Pushkin's Boris Godunov in its historical context and analyze how this is reflected in the character network
Resources (v1 API)
The FastMCP server exposes the following resources:
info://- API information and version detailscorpora://- List of all available corporacorpus://{corpus_name}- Information about a specific corpuscorpus_metadata://{corpus_name}- Metadata for all plays in a corpusplays://{corpus_name}- List of plays in a specific corpusplay://{corpus_name}/{play_name}- Information about a specific playplay_metrics://{corpus_name}/{play_name}- Network metrics for a specific playcharacters://{corpus_name}/{play_name}- List of characters in a specific playspoken_text://{corpus_name}/{play_name}- Spoken text in a play (with optional filters)spoken_text_by_character://{corpus_name}/{play_name}- Text spoken by each characterstage_directions://{corpus_name}/{play_name}- Stage directions in a playnetwork_data://{corpus_name}/{play_name}- Network data in CSV formatrelations://{corpus_name}/{play_name}- Character relation data in CSV formatcharacter_by_wikidata://{wikidata_id}- List plays containing a character by Wikidata IDfull_text://{corpus_name}/{play_name}- Full text of a play in plain text formattei_text://{corpus_name}/{play_name}- Full TEI XML text of a play
Tools (v1 API)
The FastMCP server provides the following tools:
search_plays- Search for plays based on a querycompare_plays- Compare two plays in terms of metrics and structureanalyze_character_relations- Analyze character relationships in a playanalyze_play_structure- Analyze the structure of a playfind_character_across_plays- Find a character across multiple playsanalyze_full_text- Analyze the full text of a play, including dialogue and stage directions
Prompt Templates (v1 API)
The FastMCP server includes these prompt templates:
analyze_play- Template for analyzing a specific playcharacter_analysis- Template for analyzing a specific characternetwork_analysis- Template for analyzing a character networkcomparative_analysis- Template for comparing two playsgender_analysis- Template for analyzing gender representation in a playhistorical_context- Template for analyzing the historical context of a playfull_text_analysis- Template for analyzing the full text of a play
How It Works
This project uses the official Model Context Protocol Python SDK to build an MCP server that exposes resources and tools that Claude can use to interact with the DraCor API.
When you ask Claude a question about dramatic texts, it can:
- Access resources like corpora, plays, characters, and networks
- Use tools to search, compare, and analyze plays
- Provide insights and visualizations based on the data
The DraCor API is publicly accessible, so no authentication is required.
Rate Limiting
Be mindful of DraCor's rate limiting policies. The server includes optional rate limiting settings that can be configured in the .env file.
Troubleshooting
If you encounter issues:
- Ensure you're using Python 3.10 or higher
- Try running in development mode to debug:
mcp dev dracor_mcp_fastmcp.py - Check the DraCor API status at https://dracor.org/doc/api
Prompt to use with MCP
"Your task is to analyze historical plays from the DraCor database to identify character ID tagging issues. Specifically:
- Select a play from the DraCor database and perform a comprehensive analysis of its character relations, full text, and structure.
- Identify all possible inconsistencies in character ID tagging, including:
- Spelling variations of character names
- Character name confusion or conflation
- Historical spelling variants
- Discrepancies between character IDs and stage directions
- Create a detailed report of potential character ID tagging errors in a structured table format with the following columns:
- Text ID (unique identifier for the play)
- Current character ID used in the database
- Problematic variant(s) found in the text
- Type of error (spelling, variation, confusion, etc.)
- Explanation of the issue
do it for this text: [playname]"
License
MIT
Acknowledgements
This project uses:
- Model Context Protocol Python SDK for building the MCP server
- DraCor API v1 for dramatic text and network data
- Drama Corpora Project (DraCor) for providing the underlying data and API