_{Exon the Axolotl}

VepClin-MCP

VepClin-MCP is a terminal-based bioinformatics CLI chat tool that integrates Ensembl VEP, NCBI ClinVar, a custom-built MCP server layer, and OpenRouter's NVIDIA Nemotron 3 Ultra model to look up variant consequences and clinical significance, presenting the results as clear, readable summaries in a Rich-powered CLI.

Features • Technologies • Architecture • Quick Install • Source Install • How to Run

• NVIDIA Nemotron 3 Ultra powered chat interface
• Ensembl VEP integration for genomic and transcript-qualified HGVS variant consequence lookup
• ClinVar integration for clinical significance, oncogenicity, review status, traits, & variation IDs
• Export batch results as CSV, TSV, annotated VCF, or multi-sheet Excel (.xlsx)
• Single-variant PDF report generation
• Gruvbox-styled Rich terminal interface with readable panels, tables, & status messages, featuring pixel-art mascot Exon the Axolotl
• MCP server layer exposing custom reusable variant annotation tools

• CLI/UI: Python, Rich, Questionary
• MCP Layer: FastMCP
• HTTP/API Client: httpx
• AI: OpenRouter API, NVIDIA Nemotron 3 Ultra
• Variant Annotation: Ensembl VEP REST API
• Clinical Data: NCBI ClinVar via Biopython Entrez
• Excel/PDF Export: openpyxl, ReportLab
• Storage: Local config.json file for genome build & transcript-mode preferences
• Packaging: setuptools, pyproject.toml
• Testing: pytest, FastMCP test client

---
---
config:
  layout: dagre
  theme: redux-dark-color
  look: redux
  fontFamily: '''Source Code Pro Variable'', monospace'
  themeVariables:
    fontFamily: '''Source Code Pro Variable'', monospace'
---
flowchart LR
    User[User] --> CLI[VepClin CLI<br/>terminal_ui.py<br/>Rich + Questionary]

    CLI --> Runner[Chat + Command Loop<br/>llm_runner.py<br/>Handles chat, slash commands, tool calls]
    Runner --> MCP[Embedded FastMCP Server<br/>mcp_server.py<br/>Exposes variant tools]
    MCP --> Client[VariantClient<br/>variant_client.py<br/>Runs VEP + ClinVar lookups]

    Client --> VEP[Ensembl VEP REST API<br/>Variant consequences]
    Client --> ClinVar[NCBI ClinVar / Entrez<br/>Clinical significance]

    VEP --> Results[Annotated Variant Results<br/>VEP consequence data]
    ClinVar --> Results[Annotated Variant Results<br/>ClinVar clinical data]

    Results --> Runner
    Runner --> CLI

    Runner --> Settings[Session Settings<br/>session_config.py<br/>Genome build + transcript mode]
    Runner --> Exports[Export Helpers<br/>exporter.py<br/>CSV / TSV / VCF / XLSX / PDF]

    Exports --> Files[Local Output Files<br/>Reports + batch exports]

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install git+https://github.com/shivankvirdi/VepClin-MCP.git

python3 -m venv .venv
source .venv/bin/activate
python -m pip install git+https://github.com/shivankvirdi/VepClin-MCP.git

OPENROUTER_API_KEY is required for the LLM chat interface (https://openrouter.ai/).
NCBI_EMAIL is recommended for consistent NCBI Entrez/ClinVar requests.
NCBI_API_KEY is optional, but recommended for higher ClinVar request limits (https://www.ncbi.nlm.nih.gov/datasets/docs/v2/api/api-keys/).

[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or...", "User")
[Environment]::SetEnvironmentVariable("NCBI_EMAIL", "you@example.com", "User")
[Environment]::SetEnvironmentVariable("NCBI_API_KEY", "...", "User")

# Zsh
echo 'export OPENROUTER_API_KEY="sk-or..."' >> ~/.zshrc
echo 'export NCBI_EMAIL="you@example.com"' >> ~/.zshrc
echo 'export NCBI_API_KEY="..."' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'export OPENROUTER_API_KEY="sk-or..."' >> ~/.bashrc
echo 'export NCBI_EMAIL="you@example.com"' >> ~/.bashrc
echo 'export NCBI_API_KEY="..."' >> ~/.bashrc
source ~/.bashrc

git clone https://github.com/shivankvirdi/VepClin-MCP.git
cd VepClin-MCP
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .
Copy-Item .env.example .env

git clone https://github.com/shivankvirdi/VepClin-MCP.git
cd VepClin-MCP
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env

Follow .env.example and add your API keys & email to VepClin-MCP/.env in the repo root.

Run the terminal chat CLI:

vepclin

Most users don't need this. The vepclin chat CLI starts and uses the MCP tools automatically.

vepclin-server

If you installed from source, you can also run the server directly:

python backend/mcp_server.py