tei-mcp

<p align="center"> <img src="banner.png" alt="tei-mcp — TEI P5 for AI agents" width="600"> </p>

<p align="center"> <a href="https://doi.org/10.5281/zenodo.19039570"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19039570-blue" alt="DOI"></a> <a href="https://pypi.org/project/tei-mcp/"><img src="https://img.shields.io/pypi/v/tei-mcp" alt="PyPI version"></a> <a href="https://github.com/Pantagrueliste/tei-mcp/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/tei-mcp" alt="License"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible"></a> <a href="https://tei-c.org/guidelines/"><img src="https://img.shields.io/badge/TEI-P5-orange" alt="TEI P5"></a> </p>

An MCP server that helps AI agents read and write valid TEI XML. It parses the TEI P5 specification and exposes 16 tools for element lookup, attribute resolution, content model expansion, nesting validation, document validation, and ODD customisation.

Features

• Element, class, macro, and module lookup with case-insensitive matching and typo suggestions
• Attribute resolution across the full TEI class hierarchy (local + inherited)
• Content model expansion into structured trees with class and macro resolution
• Nesting validation (direct parent-child and recursive reachability with path tracking)
• Document validation against TEI P5: content models, attributes, closed value lists, reference integrity, deprecation warnings
• Single-element validation for incremental editing workflows
• ODD customisation support: load a project ODD to constrain the schema (moduleRef filtering, elementSpec delete/change, attDef modifications)
• Regex search across all entity types (elements, classes, macros, modules)
• Deprecation awareness with validUntil dates and replacement suggestions
• Attribute suggestion by intent description (keyword matching against attribute descriptions)

Requirements

• Python 3.10+
• uv (recommended) or pip

Installation

The quickest way is via uvx, which fetches and runs the server automatically:

uvx tei-mcp

Or install from PyPI:

pip install tei-mcp

Or clone and install from source:

git clone https://github.com/Pantagrueliste/tei-mcp.git
cd tei-mcp
uv sync

On first run, the server downloads p5subset.xml from the TEI website (~5 MB) and caches it locally.

Usage

tei-mcp works with any MCP-compatible client. Add the following to your client's MCP server configuration:

{
  "mcpServers": {
    "tei": {
      "command": "uvx",
      "args": ["tei-mcp"]
    }
  }
}

Where this file lives depends on your client:

Client	Configuration file
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Claude Code	.mcp.json in your project directory
Cursor	.cursor/mcp.json in your project directory
Windsurf	~/.codeium/windsurf/mcp_config.json
Other clients	Consult your client's MCP documentation

Standalone

uvx tei-mcp

The server communicates over stdio using the MCP protocol.

Tools

Tool	Description
lookup_element	Look up an element by name (e.g., persName)
lookup_class	Look up a class by name (e.g., att.global)
lookup_macro	Look up a macro by name (e.g., macro.paraContent)
list_module_elements	List all elements in a module (e.g., namesdates)
search	Regex search across all TEI entities
list_attributes	Resolve all attributes for an element (local + inherited)
class_membership_chain	Show the full class hierarchy chain
expand_content_model	Expand content model into a structured tree
valid_children	List all valid direct children of an element
check_nesting	Check if an element can appear inside another
check_nesting_batch	Check multiple nesting pairs in one call
suggest_attribute	Find relevant attributes by intent description
validate_document	Validate a TEI XML file against the spec
validate_element	Validate a single element in context
load_customisation	Load an ODD customisation file
unload_customisation	Clear the loaded customisation

Most tools accept use_odd=True to query the customised schema instead of the full TEI P5.

ODD Customisation

Load a project-specific ODD file to constrain the schema:

1. Call load_customisation("/path/to/my-project.odd")
2. Use use_odd=True on subsequent tool calls
3. Call unload_customisation() to revert to the full spec

Supported ODD features:

• moduleRef with include / except filtering
• elementSpec mode="delete" to remove elements
• elementSpec mode="change" with attDef modifications (delete, change, add)
• Closed/semi value list restrictions

Environment Variables

Variable	Default	Description
TEI_ODD_PATH	—	Path to a local p5subset.xml (skips download)
TEI_ODD_URL	TEI-C GitHub URL	Custom URL for the ODD file

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage info
uv run pytest -v

License

MIT