BioCartoon is a free and open-source tool for creating biology figures with illustrations. We compile existing open biology-focused illustration resources and introduce our own illustrations in a single database with a graphical interface for search and figure generation.
This repository holds the icon database and the biocartoon command-line interface. The desktop app, web app, and website are in .
BioCartoon's asset database: 13,000+ open-licensed scientific illustrations, the catalog crate, CLI and MCP server, and the upload Worker
The biocartoon command searches the published catalog from a shell:
pip install biocartoon
If your shell then says biocartoon: command not found, pip put the program in a folder that is
not on your PATH (pip names it in a warning near the end of its output): add that folder to PATH,
or install with pipx install biocartoon or uv tool install biocartoon, which handle PATH for you.
The package is the compiled program alone, with no Python dependencies. To build it from source
instead, run cd catalog && cargo build --release (giving target/release/biocartoon). This
build searches icons; its MCP server also lists the shared slide templates. The BioCartoon desktop
editor ships a fuller biocartoon that adds templates to search and the app command.
On Windows, the build also needs the Visual Studio Build Tools with the C++ workload
(winget install Microsoft.VisualStudio.2022.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"),
and must run from PowerShell or cmd: Git Bash's own link command shadows the MSVC linker.
biocartoon search "TERM": icons and templates matching TERM, best first. With no TERM it pages
through everything.
--icons / --templates: only that kind
--tags T,...: icons and templates with one of these tags (a whole tag, any case)
--source S: icons from a collection (a code or name from biocartoon --sources)
--author A: icons by an author (part of the name, any case)
--category C: icons in a category (a slug from biocartoon --categories)
--subcategory S: icons in a subcategory (a slug from biocartoon --categories)
--source-category [S:]C: icons in a collection's own category (from biocartoon --source-categories)
--license L: icons under a license (CC-BY-4.0, CC0-1.0, ...)
--file-type svg|png: icons published as SVG, or as a PNG only
Repeat a filter for several values: an icon matching any of them passes. An icon has to pass
every filter given.
--sql: run TERM as read-only SQL on the catalog.
biocartoon get ID: everything about one icon: license, credit, PNG/SVG URLs, colour variants
biocartoon fetch ID: download the SVG, or the PNG when the source publishes no SVG (--png or --svg for that type only, --out FILE|DIR, --max-side N for a smaller PNG)
biocartoon sync: download the newest published catalog
biocartoon bulk-download: the whole catalog into one folder with a README (contents, licenses, and the equivalent curl/sqlite3 commands, which it also prints as it goes); running it again fetches only what is missing
--files all|metadata|artwork|icons|templates: what to get (comma-separate several; artwork is icons and templates; default all)
--metadata-ext sqlite|csv|tsv|xlsx|json: the icon and template catalogs' format (default sqlite)
--artwork-ext png|svg: sets both of the next two (templates have no SVG, so they come as PNG)
--icons-ext svg|png: default svg, with a PNG where the source publishes no SVG
--templates-ext png|biocartoon: the thumbnail (default), or a .biocartoon file the editor opens
--output-dir DIR (default ./biocartoon-catalog), --jobs N (parallel downloads, default 8), --limit N (the first N of each, to try it out)
biocartoon upload FILE...: submit images files/folders to the database (approval required to merge in); --tags T,... adds words to find them by
biocartoon app CMD [JSON]: drive the running desktop editor (editor's build only) --- requires the desktop app
biocartoon mcp: serve the same tools over MCP, mostly for agents (e.g., claude mcp add biocartoon -- biocartoon mcp)
biocartoon --version: the program's version, and when the local catalog was published and downloaded
biocartoon --sources: list icon sources for biocartoon search --source S
biocartoon --categories: list icon categories for biocartoon search --category C
biocartoon --source-categories: list the collections' own categories for biocartoon search --source-category S:C
biocartoon search --sql # the schema
biocartoon search "select license, count(*) as n from assets group by license order by n desc"
# warning: running the search term as SQL; pass --no-sql to search for the words instead
biocartoon search --sql "select id, title from assets where svg_key is not null and title like '%ribosome%'"
biocartoon search "with dendrites" --no-sql # words, even though it starts with WITH
From a script: every command takes --json, and search results come back as
{"icons": [...], "templates": [...]}:
# download the SVG of the best match that has one (Servier and uploads are PNG only)
mkdir -p icons
for t in neuron astrocyte microglia; do
id=$(biocartoon search "$t" --icons --limit 10 --json | jq -r '[.icons[] | select(.svg_url)][0].id')
biocartoon fetch "$id" --svg --out icons/
done
biocartoon get BA001505 --json | jq -r .credit # the attribution line to print
Drive the running desktop editor (editor's build only):
biocartoon app state # page size and every item on the slide
biocartoon app insert_asset '{"asset":"BA001505","x":200,"y":120,"width":300}'
biocartoon app move_items '{"ids":[3],"dx":48}'
biocartoon app render '{"path":"slide.png"}'
Download the whole catalog (well over 1 GB), or parts of it:
biocartoon bulk-download # everything, into ./biocartoon-catalog
biocartoon bulk-download --files metadata --metadata-ext xlsx # the catalogs as spreadsheets
biocartoon bulk-download --files icons --icons-ext png --output-dir icons/
biocartoon bulk-download --files templates --templates-ext biocartoon # templates to open in the editor
Keep the local catalog current, and connect an assistant:
biocartoon sync
claude mcp add biocartoon -- biocartoon mcp
Repository Structure
catalog/ Rust crate biocartoon-catalog: the catalog library, the `biocartoon` CLI and MCP server
src/catalog.rs the SQLite catalog and the search over it (shared with the editor, so ranking matches)
src/query.rs synchronous catalog access for the CLI and MCP server
src/cli.rs the `biocartoon` commands
src/mcp.rs the MCP server (`biocartoon mcp`)
src/taxonomy.rs BioCartoon's own categories, mapped from each source's
src/templates.rs the published slide templates
src/upload.rs `biocartoon upload`: submits images to the submissions Worker
pyproject.toml packages the binary for PyPI (`pip install biocartoon`)
data/ Python pipeline that builds and publishes the catalog
scrape_sources.py download Bioicons, Health Icons, OpenMoji, Reactome, SciDraw, Servier
scrape_bioart.py download NIH NIAID BioArt Source
rasterize.py render SVGs to PNGs
build_assets_db.py build data/assets.sqlite (the master database) from the scrapes
upload_r2.py upload asset files to the R2 bucket (resumable)
uploads.py collect approved community contributions from the bucket
publish_catalog.py publish the trimmed, gzipped catalog to R2 for the app and CLI
sync.py incremental sync of new upstream assets (add-only)
publish_poll.py runs publishes queued with "Publish catalog now" on the review page
refresh_credits.py rewrite every asset's credit line
readme_stats.py regenerate the resources table above
config.py bucket names, URLs and other brand-dependent settings
requirements.txt Python packages for the pipeline (`pip install -r data/requirements.txt`)
schedule/ installs a weekly launchd job that runs sync.py (+ the publish poller)
worker/ Cloudflare Workers (TypeScript) for community contributions
src/submit.ts api.biocartoon.com: validate, rate-limit and hold submissions for review
src/review.ts review.biocartoon.com: approve or reject (behind Cloudflare Access)
src/publish.ts copies an approved submission into the public bucket
src/publish_requests.ts the "Publish catalog now" queue the Mac polls
src/stars.ts star counts on catalog assets
migrations/ D1 database schema
test/ unit tests (`npm test`)
.github/workflows/ CI tests and the PyPI release
Database Structure
The catalog is published as two gzipped SQLite files, built from the master database
(data/assets.sqlite) by data/publish_catalog.py. File keys (svg_key, png_key, json_key,
thumb_key) are paths in the public bucket, so a file lives at https://assets.biocartoon.com/<key>.
assets.sqlite.gz
One row per icon in the assets table. Only rows that are uploaded to the bucket and have a PNG are published.
column
type
description
id
TEXT, primary key
two letters for the source (BA bioart, BI bioicons, HI healthicons, OM openmoji, RE reactome, SD scidraw, SV servier, UG user upload, BC an upload in the official BioCartoon library), then a number unique across the catalog (e.g. BA001505); never reused
source
TEXT
short source name: bioart, bioicons, healthicons, openmoji, reactome, scidraw, servier, user
source_name
TEXT
display name of the source (e.g. Servier Medical Art)
source_id
TEXT
the asset's id in the upstream collection; unique together with source
title
TEXT
asset title
variant
TEXT
BioArt colour scheme or Health Icons style, when the source has variants
description
TEXT
upstream description, if any
category
TEXT
the source's category path (e.g. Anatomy and The Human Body / Cardiovascular system / Arteries)
tags
TEXT
JSON array of keywords (the source's, or the uploader's)
bucket key of the SVG; NULL for raster-only assets
png_key
TEXT
bucket key of the PNG
png_is_raster
INTEGER
1 if the PNG was rendered by us from the SVG
png_width, png_height
INTEGER
PNG size in pixels
svg_bytes, png_bytes
INTEGER
file sizes
svg_sha256, png_sha256
TEXT
file checksums
svg_local, png_local
TEXT
build-time paths under data/; empty in the published catalog
extra
TEXT
JSON of source-specific fields (e.g. BioArt accession and collection)
uploaded_at
TEXT
ISO 8601 time the files were uploaded to the bucket
stars
INTEGER
star count from users of the app
Indexes cover source, license, category and the unique pair (source, source_id).
assets_fts is an FTS5 full-text index (Porter stemming) over title, description, tags,
category and variant, joined to assets by rowid:
SELECT a.id, a.title, a.license, a.png_key
FROM assets_fts JOIN assets a ON a.rowid = assets_fts.rowid
WHERE assets_fts MATCH 'mitochondria' ORDER BY rank LIMIT 10;
templates.sqlite.gz
One row per slide template in the templates table.
column
type
description
id
TEXT, primary key
<slug>-<hash> (e.g. eukaryotic-cell-5a1e09d5a6)
title
TEXT
template title
description
TEXT
short description
category
TEXT
BioCartoon category (e.g. Cell biology)
tags
TEXT
JSON array of keywords the author gave it ([] for none)
author
TEXT
template author
license
TEXT
normalized license, as in assets
created_at
TEXT
ISO 8601 creation time
json_key
TEXT
bucket key of the template document (templates/<id>/template.json)
thumb_key
TEXT
bucket key of the thumbnail (templates/<id>/thumb.png)
json_local, thumb_local
TEXT
build-time paths; empty in the published catalog
A meta key–value table (k, v) is reserved for catalog metadata.
License
Copyright (c) 2026 Joseph Rich. This repository is open source under the BSD 2-Clause License. The editor in biocartoon-app is under the GNU AGPL v3.0. Third-party illustrations and icons keep their own licenses --- see NOTICE.md.
Contributing
Contributions are welcome --- see CONTRIBUTING.md. Contributors keep the copyright
in their work, and artists are credited under the name they choose.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Biocartoon?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Biocartoon necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Biocartoon?
Biocartoon se ejecuta localmente por stdio.
¿Cuándo se comprobó Biocartoon por última vez?
Última comprobación: 2026-10-28. BioCartoon's asset database: 13,000+ open-licensed scientific illustrations, the catalog crate, CLI and MCP server, and the upload Worker