uniprotptmpy

uniprotptmpy wraps the UniProt post-translational modification (PTM) controlled vocabulary in a typed Python API, so proteomics tooling can look up PTMs by accession, name, or free text without writing a parser for UniProt's ptmlist.txt flat file. It ships with the full vocabulary bundled in, so it works fully offline.

Highlights

• Bundled, offline data — 750 PTM entries shipped with the package; no network calls needed
• Zero core dependencies — pure Python, pip install and go
• Typed, immutable models with py.typed (PEP 561) for IDE autocomplete and static checking
• Rich lookups — by accession (PTM-0450), exact name, free-text search across name/target/keywords, subscript access, and iteration
• Formula helpers computed for you (elemental composition dicts, ProForma-style formula strings)
• Round-trip export to TSV/CSV and back to the original ptmlist.txt format
• Online browser — search, sort, and inspect every term, no install required
• Hosted REST API + MCP server at uniprot.tacular.dev (API docs, MCP endpoint https://uniprot.tacular.dev/mcp), no install required
• Optional local FastAPI + MCP server (pip install uniprotptmpy[server]) to expose the database over HTTP or to LLM tools

Install

pip install uniprotptmpy

Or with uv:

uv add uniprotptmpy

Requires Python 3.12+. No third-party dependencies for the core package. pip install "uniprotptmpy[link]" adds psimodpy and unimodpy, for entry.resolve(). entry.get_mass() is always UniProt's own mass; use resolve() for a linked one.

Quick Example

from uniprotptmpy import load

db = load()                   # bundled PTM database, no download needed
print(len(db))                # 750

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

# Lookup by exact 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")
print(len(results))           # 17

# Entries whose monoisotopic mass is within 0.01 Da of 79.966, on S, T or Y
for entry, error in db.search_mass(79.966, site="STY")[:3]:
    print(entry.name, round(error, 4))   # Phosphoserine -0.0003 ...
db.search_mass(42.010565, site="K")    # [(N6-acetyllysine, ~0.0)]

# Links to PSI-MOD and Unimod (resolve() needs: pip install "uniprotptmpy[link]")
entry = db.get_by_name("Phosphoserine")
print(entry.psimod_ids, entry.unimod_ids)  # ('MOD:00046',) ('UNIMOD:21',)
print(entry.resolve("unimod")[0].name)     # Phospho

# Dict-style access, iteration, and formula helpers
entry = db["PTM-0450"]
print(db.get("missing"))      # None; the default, instead of KeyError
print("phosphoserine" in db)  # True; accepts db[key] keys or a PtmEntry
hydroxy = db.get_by_id("PTM-0476")
print(hydroxy.correction_formula)  # O1
print(hydroxy.dict_composition)    # {'O': 1}
print(hydroxy.proforma_formula)    # O

More

Downloading the latest data, TSV/CSV export, ptmlist.txt round-trip

from uniprotptmpy import download, load, write_tsv, write_ptmlist, parse_ptm_list

# Download the latest list from UniProt's FTP site
path = download()   # ~/.cache/uniprotptmpy/ptmlist.txt
db = load(path)

# Write every entry to TSV (or CSV)
db.write_tsv("ptms.tsv")
db.write_tsv("ptms.csv", delimiter=",")

# Round-trip back to the original UniProt flat-file format
db.write_ptmlist("out/ptmlist.txt")
db2 = parse_ptm_list("out/ptmlist.txt")  # identical entry count and fields

Local HTTP API and MCP server (pip install uniprotptmpy[server])

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

This starts a FastAPI app exposing the database as both a JSON REST API (GET /api/entries/{id}, /api/search, /api/entries/by-name/{name}, …) and an MCP endpoint at POST /mcp with get_by_id, get_by_name, and search tools, for pointing LLM clients directly at the UniProt PTM vocabulary:

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

The same app is hosted at https://uniprot.tacular.dev (REST under /api/..., interactive docs at /docs), so you can skip the local install and point a client straight at the public MCP endpoint:

claude mcp add uniprot-ptm https://uniprot.tacular.dev/mcp --transport http

Full API reference

Symbol	Description
load(source=None, *, refresh=False, cache=False)	Load the PTM database. Uses bundled data by default; refresh=True downloads the current release first; cache=True parses the bundled file once and returns the same (read-only) database on later calls.
download(dest=None, *, force=False)	Download the latest ptmlist.txt from UniProt FTP (reuses an existing file unless force=True).
parse_ptm_list(path)	Parse a ptmlist.txt file into a PtmDatabase.
write_tsv(entries, path, *, delimiter)	Write entries to a TSV (or CSV) file.
write_ptmlist(entries, path)	Write entries back to UniProt ptmlist.txt flat-file format.
PtmDatabase	Indexed collection with get_by_id(), get_by_name(), search(), search_mass(delta, *, tolerance=0.01, tolerance_unit="da", site=None, position=None) ((entry, error) pairs within tolerance Da), get_by_site(site) (one residue), write_tsv(), write_ptmlist(), iteration, and len().
PtmEntry	Frozen dataclass with all PTM fields, plus accession, dict_composition, proforma_formula ("HO3P"), psimod_ids and unimod_ids properties; get_mass(*, monoisotopic=True) (UniProt's own mass or None); resolve("psimod" | "unimod") returns the linked entries (needs the [link] extra).
db.get(key, default=None)	db[key], or default instead of KeyError.
key in db	Test membership with any key accepted by db[key] (integer ID, accession, or name), or a PtmEntry.
UniprotPtmError, UniprotPtmParseError, UniprotPtmKeyError	Package exceptions; the parse error is also a ValueError, and UniprotPtmKeyError (raised by db[key] on a miss) is also a KeyError.
FeatureType	StrEnum: CROSSLNK, MOD_RES, LIPID, CARBOHYD, DISULFID.
CrossReference	Frozen dataclass with database and accession fields.
TaxonomicRange	Frozen dataclass with taxon_name, tax_id, description, and raw fields.

See CHANGELOG.md for release history.

Data Source

Term data comes from UniProt's PTM controlled vocabulary list, maintained by the UniProt Consortium. See uniprot.org for the vocabulary's own license and citation guidance.

Related Projects

Part of the tacular-omics family of proteomics PTM-vocabulary packages:

Package	Description
unimodpy	Parse and query the UNIMOD mass spectrometry modifications database
psimodpy	Parse and query the PSI-MOD protein modification ontology
tacular	Broader MS-proteomics lookup library (amino acids, elements, fragment-ion masses) that bundles its own copies of UniProt-PTM alongside UNIMOD, PSI-MOD, RESID, XLMOD, and GNOme; the base library for peptacular and paftacular

Citation

If uniprotptmpy is useful in your research, please cite it — see CITATION.cff or use the "Cite this repository" button on GitHub. Releases are archived on Zenodo (DOI badge above).

License

MIT