uniprotptmpy

Python library for parsing and querying the UniProt post-translational modification (PTM) controlled vocabulary.

• Zero core dependencies
• Bundled PTM data (748 entries) — works offline out of the box
• Typed, immutable data models (py.typed / PEP 561)
• TSV/CSV export and round-trip ptmlist.txt writer
• Optional FastAPI / Model Context Protocol server (pip install uniprotptmpy[server])

Online Viewer

Click Me!

The same database is also reachable as a hosted REST + MCP service — see HTTP API and MCP Server below.

Installation

pip install uniprotptmpy

Or with uv:

uv add uniprotptmpy

Requires Python 3.12+. No third-party dependencies.

Quick Start

from uniprotptmpy import load

# Load the bundled PTM database
db = load()
print(len(db))  # 748

# Look up by accession
entry = db.get_by_id("PTM-0450")
print(entry.name)  # (2-aminosuccinimidyl)acetic acid (Asn-Gly)

# Look up by name (case-insensitive)
entry = db.get_by_name("phosphoserine")
print(entry.id)  # PTM-0253

# Free-text search across name, ID, target, and keywords
results = db.search("acetylation")

# Dict-style access (raises KeyError if not found)
entry = db["PTM-0450"]

# Iterate all entries
for entry in db:
    print(entry.id, entry.name)

Chemical Formulas

entry = db.get_by_id("PTM-0476")  # 3-hydroxyproline
print(entry.correction_formula)   # O1
print(entry.dict_composition)     # {'O': 1}
print(entry.proforma_formula)     # O

Exporting to TSV/CSV

# Write all entries to a tab-separated file
db.write_tsv("ptms.tsv")

# Or CSV
db.write_tsv("ptms.csv", delimiter=",")

# Standalone function also available
from uniprotptmpy import write_tsv
write_tsv(db, "ptms.tsv")

Writing back to ptmlist.txt format

# Round-trip: write entries back to the original UniProt flat-file format
db.write_ptmlist("out/ptmlist.txt")

# Re-parse the written file — identical entry count and field values
from uniprotptmpy import parse_ptm_list
db2 = parse_ptm_list("out/ptmlist.txt")

# Standalone function
from uniprotptmpy import write_ptmlist
write_ptmlist(db, "out/ptmlist.txt")

Downloading the Latest Data

from uniprotptmpy import download, load

path = download()   # downloads to ~/.cache/uniprotptmpy/ptmlist.txt
db = load(path)     # load from the downloaded file

HTTP API and MCP Server

The optional [server] extra ships a FastAPI app that exposes the same database over a JSON REST API and over the Model Context Protocol so language-model tools can query the UniProt PTM vocabulary directly.

pip install uniprotptmpy[server]
uvicorn uniprotptmpy.server.app:app --reload

REST endpoints

Search responses contain just {id, name, feature_type, target, monoisotopic_mass} to keep token cost low; call /api/entries/{id} on any hit for the full record (including taxonomic ranges and cross-references).

MCP server

The same FastAPI app mounts an MCP endpoint at POST /mcp with three tools:

Tool responses use MCP's structured-output mechanism: the server emits an outputSchema per tool in tools/list and returns both structuredContent (typed Pydantic instance) and content (text fallback) on tools/call, so LLM clients can parse the response without re-reading the JSON string.

Configure your MCP-aware client to point at http://localhost:8000/mcp (or wherever you deploy the app). Example with the Anthropic CLI:

claude mcp add uniprot-ptm http://localhost:8000/mcp --transport http

API Overview

Development

just install   # install dependencies with uv
just lint      # ruff check
just format    # ruff format
just ty        # ty type check
just test      # pytest
just check     # lint + type check + test

Related Projects

License

MIT