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"]
hydroxy = db.get_by_id("PTM-0476")
print(hydroxy.correction_formula)  # O1
print(hydroxy.dict_composition)    # {'O': 1}
print(hydroxy.proforma_formula)    # O

More

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

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

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

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

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:

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