tfbs-mcp: a Model Context Protocol server for agentic transcription factor binding site analysis

Abstract

tfbs-mcp is a Model Context Protocol (MCP) server for transcription factor (TF) binding site analysis. It exposes the steps of a binding-site study as 33 tools that a large language model (LLM) client, such as Claude Code, calls directly. Those steps run from peak extraction and dataset preparation through model training, attribution analysis, motif scanning and structure-based binding energy to validation against external peak sets and disease variants. Workflow managers such as Snakemake and Nextflow suit a fixed dependency graph that is rerun across samples. An exploratory session changes the graph with every question. With tfbs-mcp the researcher states the TF, the data and the question in natural language. The LLM then: selects the tools; fills parameters with the defaults stated in the tool descriptions; runs the work locally or as SLURM jobs; explains each choice. Naming a decision overrides the default, without editing a configuration file. Most tools derive their output directories from their inputs and return the paths they wrote, so calls chain without a workflow script. The server runs on the machine that holds the data: a laptop, a workstation or a SLURM login node. It downloads only structures, and uploads nothing unless Weights and Biases logging is switched on. SLURM is optional: the in-process tools work anywhere, and training runs locally or as a job. The 33 tools, in six layers Inference (10 tools): loading checkpoints, scoring, DeepLiftShap and InputXGradient attribution with Captum, in silico mutagenesis and motif marginalisation with tangermeme, FIMO motif scanning, and metrics. SLURM management (5 tools): submitting, inspecting, reading the logs of and cancelling cluster jobs; a watch helper returns the next status call for the client to schedule. Training (4 tools): LightningCLI configurations from templates for 13 architectures, local or SLURM training, Weights and Biases sweeps, and evaluation on the test split. Data pipeline (7 tools): peak, GC-matched negative and variant windows cut from a BED file and a genome; dataset preparation; seqlet, epistasis and convolutional-filter analyses. Structure-based (3 tools): TF-DNA complexes from the PDB (AlphaFold DB supplies protein-only models); FoldX binding energy; a bigWig track from a sliding-window scan. Validation and comparison (4 tools): a ChIP-Atlas benchmark; ReMap external validation; a head-to-head comparison of the neural network, FIMO and FoldX against a JASPAR motif; a ClinVar disease-variant check. How this release was tested A real session. The application note shows a session of Claude Code driven by two prompts. On a GPU node of a SLURM cluster, it built an NKX2-1 classifier from ChIP-Atlas peaks, validated it against ReMap 2022 peaks and ClinVar variants, and called eight tools, with no hand-written configuration file or batch script. The session was recorded with an earlier commit (25a90d6). The supplement lists every call and everything that changed since. A smoke test of all 33 tools. The scripted plan docs/all_tools_plan.json calls every tool, in 49 steps on NKX2-1 data. It passed on a GPU node of the BIH cluster at the release candidate (040496a). The fix made after that run, in the sweep agent, was checked on the cluster with a one-trial sweep at 1.0.0. Version 1.0.1 corrects the coding filter of the ClinVar check, which had let ClinVar’s “nonsense” (stop-gained) variants through as non-coding. Unit and contract tests. The pytest suite runs in GitHub Actions on Python 3.10 to 3.13. Installation pip install "tfbs-mcp[mcp,genomics,viz] @ git+https://github.com/sproft/tfbs-mcp@v1.0.1" tfbs-mcp --check tfbs-mcp --check verifies the installation. It also prints the command that registers the server with Claude Code and the configuration block for other MCP clients. Python 3.10 to 3.13 is supported. External programs: MEME Suite fimo: used for motif scanning when present (tangermeme’s FIMO reimplementation otherwise); the validation pipelines need the binary. FoldX: needed for structure-based scoring (academic licence). The trained NKX2-1 models of the companion study (doi:10.5281/zenodo.21399578) load directly with tfbs_load_model and run in the validation tools. Limitations The LLM that composes the workflow is non-deterministic, so the same request can produce different tool chains. A tool can also receive wrong parameters and still return a well-formed result, so a human should check the chosen chain and the key outputs. The client sends the prompt, the tool arguments and the tool results to the language-model provider. The server runs batch scripts and command-line arguments written by the LLM. The approach therefore suits trusted environments with human confirmation. Licence and citation MIT licence. Source code: https://github.com/sproft/tfbs-mcp (tag v1.0.1, commit 25840fe). Please cite this record (doi:10.5281/zenodo.23377583), and the application note once it is published.