Provides tools for interacting with and validating TEI (Text Encoding Initiative) XML documents, including element lookup, attribute resolution, content model expansion, and validation against the TEI P5 specification and ODD customizations.
tei-mcp
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-mcpOr install from PyPI:
pip install tei-mcpOr clone and install from source:
git clone https://github.com/Pantagrueliste/tei-mcp.git
cd tei-mcp
uv syncOn 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 |
|
Claude Code |
|
Cursor |
|
Windsurf |
|
Other clients | Consult your client's MCP documentation |
Standalone
uvx tei-mcpThe server communicates over stdio using the MCP protocol.
Tools
Tool | Description |
| Look up an element by name (e.g., |
| Look up a class by name (e.g., |
| Look up a macro by name (e.g., |
| List all elements in a module (e.g., |
| Regex search across all TEI entities |
| Resolve all attributes for an element (local + inherited) |
| Show the full class hierarchy chain |
| Expand content model into a structured tree |
| List all valid direct children of an element |
| Check if an element can appear inside another |
| Check multiple nesting pairs in one call |
| Find relevant attributes by intent description |
| Validate a TEI XML file against the spec |
| Validate a single element in context |
| Load an ODD customisation file |
| 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 specSupported ODD features:
moduleRefwithinclude/exceptfilteringelementSpec mode="delete"to remove elementselementSpec mode="change"withattDefmodifications (delete, change, add)Closed/semi value list restrictions
Environment Variables
Variable | Default | Description |
| — | Path to a local |
| 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 -vLicense
MIT
