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

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

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

This is the beginning of the README. Read the rest at the original. Read the full README ↗