Model Context Protocol server · Mass spectrometry
MSMCP connects AI workflows to deterministic, auditable tools for inspection, QC, search, and hypothesis testing.
It is an MCP server between your LLM client and the operations that actually need doing: exact-mass validation, adduct and isotope chemistry, spectral similarity, quality control and library search. The model plans and interprets; the tools compute — against your files, on your machine.
LLMs should reason about mass spectrometry, not perform the arithmetic. Every scientific value on this page is a tool's output rather than a model's recollection, and every derived result carries a record of how it was made. That is the standard AI-assisted mass spectrometry should be held to, and MSMCP is infrastructure for it.
How the peaks stay out of the prompt
An opaque, random, expiring handle — never an address, an id or a path.
The model carries references, job IDs and verdicts — never spectra.
Example
The transcript below is a real run of MSMCP against a real acquisition and a real spectral library. The library scan is the slow step, and it never blocks the conversation — it is dispatched as a job and polled.
“I have a peak eluting at 3.80 min, precursor m/z 315.2321, MS2. Is it Δ⁹-THC?”
load_spectrum(file_path="experiment.mzML", spectrum_index=966)
validate_precursor(theoretical_mass=315.2320, experimental_mass=315.2321)
search_library(spectrum_reference="ptr:spectrum:264a5ae9…", database_file="libraries/MASSBANK.msp", scoring_method="classical")
check_search_status(job_id="2aafd7b8…") → running …
check_search_status(job_id="2aafd7b8…") → completed
| Rank | Candidate (MassBank accession) | Cosine | q-value |
|---|---|---|---|
| 1 | Δ⁹-tetrahydrocannabinolEQ362902 · C21H30O2 | 0.8309 | 0.0125 |
| 2 | Δ⁹-tetrahydrocannabinolAU158302 · C21H30O2 | 0.7842 | 0.0125 |
| 3 | Δ⁹-tetrahydrocannabinolAU158301 · C21H30O2 | 0.6958 | 0.0333 |
| 4 | progesteroneAU107706 · C21H30O2 | 0.6922 | 0.0333 |
| 5 | progesteroneAU107702 · C21H30O2 | 0.6862 | 0.0333 |
| 6 | Δ⁹-tetrahydrocannabinolEQ362901 · C21H30O2 | 0.6827 | 0.0333 |
The report MSMCP returns leads with its own caveat: these are candidate library matches ranked by the stated scorer and significance model, not validated compound identifications. Note the competition — the runner-up candidates are progesterone, a constitutional isomer at the same precursor m/z. That is what a deterministic score plus a false-discovery threshold buys an analytical chemist: the whole field, not one confident answer.
search_library with scoring_method="classical", run against MassBank's public MSP library (63,879 spectra) read from disk, querying spectrum #966 of a Bruker maXis LC–MS/MS acquisition (RT 3.795 min, precursor m/z 315.2321, 220 peaks, m/z range 65.0382–318.2416). The ppm verdict is a fresh validate_precursor call against MassBank's reference mass. Beyond shortened IDs, relative library paths and a stand-in filename for the acquisition, the numbers are the tools' own output, unedited — and the acquisition's real filename is not published here.Why MSMCP
The model calls the tool; the tool does the chemistry. Exact masses, adduct shifts, isotope envelopes, ppm gates and cosine scores are computed by pure, unit-tested Python — the same functions every time, answering the same way. The model never invents a mass and never does the arithmetic.
The isotope envelope on this page is annotate_isotopes output for glucose; the 0.32 ppm verdict above is validate_precursor output. Neither was written by a language model.
Reproducible execution is separated from the model's variable interpretation. Fast operations return immediately; long ones — a library scan is minutes — are dispatched to a job executor and polled, so a client timeout can never truncate a result.
Every derived object carries an immutable provenance record: the operation, its parameters, the source file with reader backend and SHA-256 digest, the parent references, and the software and model versions. When an answer is wrong, you can tell whether the tool failed or the interpretation did.
MSMCP runs as a local child process on stdio: it makes no network calls of its own, stores no credentials, and ships no library data. Every file read is confined to one allowed root, under file-size and spectrum-count caps, and a path that escapes that root — symlinks included — is refused rather than read.
Its boundary is stated, not implied: the host spawns the server with your credentials, so anyone who can drive your LLM client can drive the server. Run it on a machine you own, and never expose it as a network service.
annotate_isotopes("C6H12O6")
M+1 and M+2 are shown on a separate scale; on the full-scale panel above they are 6.86 % and 1.47 % of the base peak. Values are the tool's output, reproduced without rounding.
Also verified in the tree
search_library searches the libraries you already have — no upload, no hosted service.Get started
MSMCP is not published to PyPI yet, so there is no package to install and no binary to download: the path today is a clone, synced with uv. You need uv and Python 3.13, which .python-version pins for you. No API key, no account, no server to sign up for.
git clone https://github.com/janusson/MSMCP.git
cd MSMCP
uv sync --extra dev # creates .venv, installs runtime + dev dependencies
uv run msmcp # serves MCP over stdioOptional extras: --extra chem adds RDKit so SMILES can be converted to a formula; embedding-based scoring needs the DreaMS model installed separately from source. Neither is required for the core server.
{
"context_servers": {
"msmcp": {
"command": "uv",
"args": ["run", "msmcp"],
"env": {}
}
}
}Shown for Zed's context_servers; any host that can spawn a stdio MCP server configures the same command and arguments.
Only cancel_search and release_reference change server state, and both advertise that on the wire.
Documentation & links
There is no separate documentation site, because two copies of a contract drift. Each link below goes to a maintained file in the repository.
Contact. There is no mailing list and no contact form. Bug reports, questions and feature discussion belong in GitHub Issues, where the answer stays searchable for the next person.