AI-native PCR primer design platform by YambaCode AB
PrimerForge designs, validates, and ranks PCR primer pairs for any gene via three interfaces: an MCP server (for Claude Code / AI agents), a FastAPI HTTP API, and a SvelteKit web UI with live streaming.
- 4 design modes: Standard PCR · qPCR (TaqMan) · RT-PCR (exon-junction) · SNP-aware
- Live pipeline streaming — watch each stage complete in real time via SSE
- Gene resolution via NCBI Gene + Nuccore (free, no account needed)
- SNP masking from dbSNP (avoids primers spanning common variants)
- Off-target specificity via local BLAST+ (human genome)
- Thermodynamic analysis via Primer3 — Tm, ΔG, dimers, hairpins
- Multi-criteria scoring (0–100) with weighted pass/fail verdicts
PrimerForge pulls from three free public sources — no proprietary database required:
| Source | What it provides | Access |
|---|---|---|
| NCBI Gene / Nuccore | Gene symbol → RefSeq transcript (mRNA, CDS, exon boundaries) | E-utilities (free; optional API key for 10 req/s) |
| dbSNP (NCBI) | Common SNPs (MAF ≥ 1%) → masked positions | E-utilities (same key) |
| BLAST+ databases | Off-target specificity vs. reference genome | One-time download (~30 GB human genome) |
User Input
gene = "BRCA1"
mode = rt_pcr
│
▼
[1] Gene Resolution (NCBI Gene → Nuccore) ~3–8 s
BRCA1 → NM_007294.4 · 7,088 nt · 24 exons
Exon-exon junction positions extracted
│
▼
[2] SNP Masking (dbSNP) ~1–2 s
47 polymorphic positions → masked with N
Prevents primer binding at common variants
│
▼
[3] Primer Design (Primer3) < 0.1 s
5 candidate pairs · spanning exon 10-11 junction
Product size 150–250 bp · Tm opt 60°C
│
▼
[4] Thermodynamic Analysis (Primer3-py) < 0.1 s
Pair 1: Fwd Tm=61.2°C · Rev Tm=60.8°C · ΔTm=0.4°C
GC 55%/50% · hairpin 38°C · cross-dimer 32°C
│
▼
[5] Specificity Check (local BLAST+) ~5–30 s / pair
Pair 1: 0 off-targets · score=100 ✓
Pair 2: 2 off-targets · score=72 ⚠
Pair 3: 0 off-targets · score=100 ✓
│
▼
[6] Validation & Ranking
Rank 1: Pair 1 · score=94/100 ✓ spans exon junction
Rank 2: Pair 3 · score=87/100 ✓
Rank 3: Pair 5 · score=81/100 ✓
Rank 4: Pair 4 · score=74/100 ⚠ high hairpin
Rank 5: Pair 2 · score=68/100 ⚠ off-targets
# Python 3.11+
python --version
# BLAST+ binaries (macOS)
brew install blast
# BLAST+ (Ubuntu/Debian)
sudo apt-get install ncbi-blast+git clone https://github.com/yambacode/primerforge
cd primerforge
pip install -e .export NCBI_EMAIL=your@email.com # required by NCBI
export NCBI_API_KEY=your_key # optional: raises rate limit to 10 req/s
export BLAST_DB_PATH=./data/blast_dbs # path to downloaded BLAST databasesmkdir -p data/blast_dbs
cd data/blast_dbs
update_blastdb.pl --decompress human_genome
# Or for a smaller test database:
update_blastdb.pl --decompress ntpython -m primerforge.serverAdd to claude_desktop_config.json:
{
"mcpServers": {
"primerforge": {
"command": "python",
"args": ["-m", "primerforge.server"],
"cwd": "/path/to/primerforge",
"env": {
"NCBI_EMAIL": "your@email.com",
"NCBI_API_KEY": "your_key"
}
}
}
}Then in Claude Code:
Design RT-PCR primers for BRCA1 spanning exon junctions
uvicorn primerforge.api:app --host 0.0.0.0 --port 8000Stream a full pipeline run:
curl --no-buffer -X POST http://localhost:8000/api/v1/stream/design-and-validate \
-H "Content-Type: application/json" \
-d '{"gene":"BRCA1","mode":"rt_pcr","num_return":5}' \
| while IFS= read -r line; do echo "$line"; doneOr call the non-streaming endpoint:
curl -X POST http://localhost:8000/api/v1/design-and-validate \
-H "Content-Type: application/json" \
-d '{"gene":"TP53","mode":"standard"}' | python -m json.toolcd primerforge-ui
cp .env.example .env # set VITE_API_BASE=http://localhost:8000
npm install
npm run dev # → http://localhost:5173# Build and push container
gcloud builds submit --tag gcr.io/YOUR_PROJECT/primerforge-api
# Deploy (free tier: 2M req/month + 360k GB-seconds)
gcloud run deploy primerforge-api \
--image gcr.io/YOUR_PROJECT/primerforge-api \
--region europe-west1 \
--allow-unauthenticated \
--memory 2Gi \
--timeout 3600 \
--set-env-vars NCBI_EMAIL=your@email.comSee cloudrun.yaml for the full service definition with Cloud Storage FUSE for BLAST databases.
cd primerforge-ui
# Set VITE_API_BASE to your Cloud Run URL in Vercel env vars
vercel deploy| Tool | Description |
|---|---|
resolve_gene |
Gene symbol/ID/accession → mRNA sequence + exon map |
fetch_snps |
SNP masking at polymorphic positions |
design_primers |
Primer3 engine (4 modes) |
check_specificity |
BLAST+ off-target scan |
analyze_thermo |
Tm, dimers, hairpins analysis |
validate_and_rank |
Multi-criteria scoring |
design_and_validate |
Full pipeline (recommended) |
| Endpoint | Method | Description |
|---|---|---|
/api/v1/stream/design-and-validate |
POST | SSE streaming — emits events per stage |
/api/v1/design-and-validate |
POST | Full pipeline (blocking) |
/api/v1/resolve-gene |
POST | Gene resolution only |
/api/v1/fetch-snps |
POST | SNP masking only |
/api/v1/design-primers |
POST | Primer3 design only |
/api/v1/check-specificity |
POST | BLAST specificity only |
/api/v1/analyze-thermo |
POST | Thermodynamics only |
/api/v1/validate-and-rank |
POST | Scoring only |
/health |
GET | Health check |
Full OpenAPI docs: http://localhost:8000/docs
pytest tests/ -vProprietary — YambaCode AB