sgserver

Command-line toolkit and MCP server for the everyday work you would do in SnapGene: inspect plasmids, find restriction sites, digest, clone, run PCR, design primers, edit sequences, auto-annotate features, verify sequencing reads and find CRISPR guides.

It is built so that humans and AI agents use the same tools: every command has --json output, and every operation is also exposed as an MCP tool.

Independent project. SnapGene is a trademark of GSL Biotech LLC. This repository contains no SnapGene software, data or licence. Features that use SnapGene's own programs call your installation (see SnapGene is optional).

Install

# CLI (+ MCP server)
uv tool install "sgserver[mcp] @ git+https://github.com/ikoshos-gland/sgserver"
# or from a clone
git clone https://github.com/ikoshos-gland/sgserver && cd sgserver
uv tool install --editable ".[mcp]"

Requires Python ≥ 3.12. Then:

sg --help
sg conf                # check installation & active capabilities (alias: sg doctor)
sg --json conf

Related MCP server: aki-mcp-sv

Quick start

sg info plasmid.gb                          # length, topology, GC, features
sg sites plasmid.gb --max-cuts 1            # unique cutters
sg digest plasmid.gb -e BamHI -e EcoRV      # fragments and ends
sg gel "cut=plasmid.gb" -e BamHI --out gel.png
sg orf plasmid.gb --min-aa 100
sg translate plasmid.gb 1653 2372
sg find plasmid.gb GGATCC                   # IUPAC letters work

Insert a gene into a vector (full example)

Directional cloning of mCherry into pUC19 with EcoRI and BamHI:

# 1) primers with restriction-site tails (GCGC helps the enzyme bind)
sg primers mCherry.gb 1 711 --fwd-tail GCGCGAATTC --rev-tail GCGCGGATCC
# 2) amplify → 731 bp with the sites at the ends
sg pcr mCherry.gb GCGCGAATTCATGGTGAGCAAGGGCGAG GCGCGGATCCCTACTTGTACAGCTCGTCC --out amp.gb
# 3) clone
sg clone pUC19.gb amp.gb -m restriction -e EcoRI -e BamHI --out pUC19-mCherry.gb

Result: 3,382 bp = 2,686 (pUC19) − 21 (removed fragment) + 717 (cut insert). Both sites are recreated and the downstream SalI/HindIII sites survive.

Pitfall. Do not write digested fragments to files and join them later: GenBank cannot store sticky ends, so the product comes out a few bp too long. Pass the whole plasmids and name the enzyme with -e.

Commands

Cloning methods: restriction, goldengate, gibson, infusion, ligation, gateway-bp, gateway-lr.

Positions are 1-based and inclusive; strand is 1 or -1.

For AI agents

JSON output

Put --json before the command:

sg --json digest plasmid.gb -e EcoRI -e BamHI

{
  "enzymes": ["EcoRI", "BamHI"],
  "fragments": [
    {"index": 1, "size_bp": 2665, "end_5": "5' overhang GATC", "end_3": "5' overhang AATT"},
    {"index": 2, "size_bp": 21,   "end_5": "5' overhang AATT", "end_3": "5' overhang GATC"}
  ],
  "files": []
}

Errors are {"error": "..."} with exit code 1. The same dictionaries come from the Python API in sgserver.api.

MCP server

sg-mcp speaks MCP over stdio and exposes 25 tools (sg_info, sg_sites, sg_digest, sg_clone, sg_pcr, sg_design_primers, sg_mutate, sg_verify_read, ...). Add it to your client:

{
  "mcpServers": {
    "sgserver": {
      "command": "sg-mcp",
      "env": { "SG_MCP_ROOT": "/path/to/your/project" }
    }
  }
}

• Claude Code: claude mcp add sgserver -e SG_MCP_ROOT=$PWD -- sg-mcp

• Codex / Gemini / others: use the JSON block above in their MCP settings.

Safety: every path an agent passes must resolve inside SG_MCP_ROOT (default: the directory the server starts in); anything else is rejected. The server uses local stdio only and opens no network port.

Skill

skills/sgserver/SKILL.md teaches an agent the commands and the pitfalls. Copy the folder into your agent's skills directory (e.g. ~/.claude/skills/).

SnapGene is optional

SnapGene is looked up in /opt/gslbiotech/snapgene; set SNAPGENE_DIR to use another location. The CLI-based features also need a valid SnapGene licence (~/.snapgene/snapgene-license.lic). Nothing from SnapGene is copied into this repository.

Validation

The tests use SnapGene's own sample project as an independent reference: it holds both the inputs of a cloning and the product SnapGene produced.

uv run python -m pytest tests -q

Without SnapGene installed, the tests that need its sample files are skipped and the synthetic-sequence tests (test_api.py, test_mcp.py) still run — this is what CI does.

Known limits

• With the SnapGene window open, convert, map and history may silently do nothing; the error message reminds you.

• history uses SnapGene's own export and falls back to pydna's parser, which can choke on ambiguous letters (N, R, Y).

• Output files are GenBank. They open in SnapGene with their features, but are not recorded in SnapGene's own cloning history.

• Methylation: an overlap with Dam/Dcm is only a warning unless the enzyme's sensitivity is known (e.g. BamHI is unaffected by Dam, MboI is blocked, DpnI requires it).

• .scf trace files cannot be read (Biopython does not support them); export them as FASTA from SnapGene first.

License

MIT