PharmaMCP
README.md
<div align="center">
# ๐ PharmaMCP
### The Unified Model Context Protocol (MCP) Server for Pharmaceutical Sciences
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](tests/)
[](CONTRIBUTING.md)
**An enterprise-grade, all-in-one AI agent toolkit tailored for Pharmacy Students, Clinical Researchers, Formulation Scientists, and Pharmacologists.**
[Features](#-key-capabilities) โข [Architecture](#-architecture) โข [Quickstart](#-quickstart--installation) โข [Client Configuration](#-how-to-connect) โข [Tool Catalog](#-comprehensive-tool-catalog) โข [Workflows](#-real-world-pharmacy-workflows)
</div>
---
## ๐ Overview
Pharmaceutical education and research demand constant context switching across fragmented platforms: literature databases (PubMed, ClinicalTrials), cheminformatics suites (PubChem, RDKit), PK/PD calculation worksheets, statistical packages (Prism, SPSS), and reference managers.
**PharmaMCP** unifies these six disjointed ecosystems into a single, high-performance **FastMCP server**. Connecting PharmaMCP to your LLM (Claude, Antigravity, Cursor, Windsurf, or ChatGPT) equips the AI with direct execution capabilities over:
1. ๐ **Paper Scraping & Literature Search** (PubMed, ClinicalTrials.gov, CrossRef DOIs, PDF parsing)
2. ๐งช **Medicinal & Analytical Chemistry** (PubChem, Lipinski Rule of 5, Veber filters, buffer recipes)
3. ๐ฉบ **Pharmacology & Toxicology** (Drug-drug interactions, $ke/t_{1/2}/AUC/C_{ss}$ PK math, ADMET evaluation)
4. ๐ **Pharmaceutics & Formulation Science** ($f_1/f_2$ dissolution similarity, release kinetics modeling, Henderson-Hasselbalch pH-solubility, pediatric dosing)
5. ๐ **Pharmaceutical Biostatistics** (Hypothesis testing, One-Way ANOVA with Tukey HSD, 4PL IC50/EC50 regression, %RSD assay precision)
6. โ๏ธ **Scientific Manuscript Writing** (Vancouver/APA citations, IMRaD section auditing, LaTeX/Markdown tables)
---
## ๐๏ธ Architecture
```mermaid
flowchart TD
subgraph Client["MCP Host Clients"]
C1["Claude Desktop"]
C2["Antigravity CLI"]
C3["Cursor / Windsurf"]
C4["Custom Python / Agent"]
end
subgraph Protocol["Transport Layer (Stdio / Streamable HTTP)"]
FastMCP["FastMCP Core Server (server.py)"]
end
subgraph Modules["PharmaMCP Specialized Modules"]
M1["๐ Literature Engine (literature.py)"]
M2["๐งช Cheminformatics Engine (chemistry.py)"]
M3["๐ฉบ Pharmacology & PK (pharmacology.py)"]
M4["๐ Pharmaceutics Science (pharmaceutics.py)"]
M5["๐ Biostatistics Engine (statistics.py)"]
M6["โ๏ธ Scientific Writing Engine (writing.py)"]
end
subgraph Services["External APIs & Scientific Compute"]
API1[("NCBI E-Utilities / PubMed")]
API2[("ClinicalTrials.gov v2")]
API3[("CrossRef DOI API")]
API4[("PubChem PUG REST API")]
COMP1["SciPy & NumPy (4PL / ANOVA / Stats)"]
COMP2["PyPDF Document Engine"]
end
C1 & C2 & C3 & C4 <--> FastMCP
FastMCP --> M1 & M2 & M3 & M4 & M5 & M6
M1 --> API1 & API2 & API3 & COMP2
M2 --> API4
M3 --> COMP1
M4 --> COMP1
M5 --> COMP1
M6 --> API1 & API3
```
---
## โก Quickstart & Installation
### 1. Clone the Repository
```bash
git clone https://github.com/contacttamilselvan25-lang/pharma-mcp.git
cd pharma-mcp
```
### 2. Create and Activate a Virtual Environment
```bash
# Windows
python -m venv venv
venv\Scripts\activate
# macOS / Linux
python3 -m venv venv
source venv/bin/activate
```
### 3. Install Dependencies
```bash
pip install -r requirements.txt
```
### 4. Verify Local Installation
Run the automated test suite to ensure all 18 test cases pass:
```bash
pytest tests/test_modules.py -v
```
---
## ๐ How to Connect
### ๐ฅ๏ธ Claude Desktop
Open your Claude Desktop configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add the `pharma_mcp` server entry:
```json
{
"mcpServers": {
"pharma_mcp": {
"command": "python",
"args": [
"C:\\path\\to\\pharma-mcp\\server.py"
]
}
}
}
```
*(Replace `C:\\path\\to\\pharma-mcp` with your actual directory path).*
---
### ๐ Antigravity CLI / Gemini Agents
Add the server entry to your `.gemini/antigravity-cli/mcp_servers.json`:
```json
{
"pharma_mcp": {
"command": "python",
"args": [
"C:/path/to/pharma-mcp/server.py"
]
}
}
```
---
### ๐ป Cursor / Windsurf
In your workspace `.cursor/mcp.json` or MCP Settings:
```json
{
"mcpServers": {
"pharma_mcp": {
"command": "python",
"args": [
"server.py"
]
}
}
}
```
---
## ๐ Comprehensive Tool Catalog (28 Tools)
### 1. ๐ Literature & Paper Scraping
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_search_pubmed` | `query`, `max_results`, `sort` | Searches NCBI PubMed for peer-reviewed studies with MeSH indexing. |
| `pharma_get_pubmed_article` | `pmid` | Retrieves complete abstract, authors, affiliations, and MeSH headings. |
| `pharma_search_clinical_trials` | `query`, `status`, `phase`, `max_results` | Searches ClinicalTrials.gov API v2 for Phase 1โ4 study records. |
| `pharma_lookup_doi` | `doi` | Queries CrossRef for publisher metadata, authors, volume, and BibTeX. |
| `pharma_extract_paper_pdf` | `pdf_path`, `max_pages` | Extracts and parses IMRaD sections from local research PDFs. |
### 2. ๐งช Medicinal & Analytical Chemistry
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_compound_lookup` | `name_or_cid` | Authoritative PubChem lookups (MW, LogP, TPSA, SMILES, InChIKey). |
| `pharma_lipinski_rule_of_five` | `query` | Calculates Lipinski (MW, LogP, HBD, HBA) and Veber oral drug-likeness. |
| `pharma_convert_chemical_id` | `identifier` | Converts across Name, CID, SMILES, InChI, and InChIKey. |
| `pharma_get_chemical_structure_image` | `query` | Generates 2D molecular structure diagram URLs & markdown embeds. |
| `pharma_calculate_buffer_recipe` | `buffer_system`, `target_ph`, `volume_ml`, `target_molarity` | Computes gram masses & protocols for USP Phosphate, Acetate & Gastric buffers. |
### 3. ๐ฉบ Pharmacology & Pharmacokinetics
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_drug_interactions_check` | `drugs` | Identifies clinical CYP450 and pharmacodynamic drug-drug interactions. |
| `pharma_calculate_pk_params` | `dose_mg`, `clearance_L_hr`, `volume_distribution_L`, `bioavailability_F`, `dosing_interval_hr` | Computes $ke, t_{1/2}, AUC, C_{ss}, C_{max}$, loading and maintenance doses. |
| `pharma_drug_target_lookup` | `drug_name` | Identifies receptor target, mechanism of action, and metabolic pathways. |
| `pharma_admet_risk_evaluator` | `molecular_weight`, `logp`, `tpsa`, `h_bond_donors`, `h_bond_acceptors`, `rotatable_bonds` | Evaluates BBB penetration, P-gp efflux liability, and estimated BCS class. |
### 4. ๐ Pharmaceutics & Formulation Science
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_dissolution_similarity_f1_f2` | `reference_profile`, `test_profile` | FDA/EMA difference factor ($f_1$) and similarity factor ($f_2$) calculation. |
| `pharma_fit_release_kinetics` | `time_points`, `percent_released` | Fits Zero-Order, First-Order, Higuchi, Korsmeyer-Peppas ($n$), and Hixson-Crowell. |
| `pharma_ph_solubility_profile` | `pka`, `drug_type`, `intrinsic_solubility_mg_mL` | Henderson-Hasselbalch ionization and solubility across stomach & intestinal pH. |
| `pharma_pediatric_dosage_calc` | `adult_dose_mg`, `age_years`, `weight_kg`, `height_cm` | Calculates pediatric doses using Young's, Dilling's, Clark's, and Mosteller BSA. |
| `pharma_excipient_compatibility_guide` | `category`, `functional_group` | Guides binder/disintegrant choices and warns against Maillard/hydrolysis degradation. |
### 5. ๐ Pharmaceutical Biostatistics
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_comparative_stats` | `group_a`, `group_b`, `group_a_name`, `group_b_name`, `paired` | Shapiro-Wilk normality check + Student's/Welch's/Mann-Whitney test + Cohen's d. |
| `pharma_one_way_anova` | `groups` | One-Way ANOVA across formulation batches with Tukey HSD post-hoc testing. |
| `pharma_fit_ic50_ec50` | `concentrations`, `responses` | 4-Parameter Logistic (4PL) regression for $IC_{50} / EC_{50}$ with 95% CI and $R^2$. |
| `pharma_sample_size_calculator` | `alpha`, `power`, `effect_size_cohens_d`, `test_type` | Calculates animal sample size per group with 10% attrition buffer for IACUC/ethics. |
| `pharma_descriptive_stats` | `data` | Computes assay precision (%RSD / CV%), Mean, SD, SEM, and USP compliance. |
### 6. โ๏ธ Scientific & Manuscript Writing
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_format_citation` | `identifier`, `style` | Formats citations in Vancouver, APA 7, Elsevier, Nature, Harvard, or BibTeX. |
| `pharma_audit_imrad_section` | `text`, `section_type` | Audits manuscript sections against ICMJE, ARRIVE, and CONSORT standards. |
| `pharma_format_scientific_table` | `headers`, `rows`, `caption`, `table_style` | Formats lab data into publication-ready Markdown or LaTeX `booktabs` tables. |
| `pharma_paraphrase_academic_phrases` | `sentence`, `context` | Upgrades informal lab notes into professional academic journal prose. |
---
## ๐ก Real-World Pharmacy Workflows
### ๐งช Scenario 1: Tablet Formulation & Dissolution Comparison
> **User**: *"We formulated a generic sustained-release tablet (F3) and compared its 8-hour dissolution against the innovator brand. Can you check if they are bioequivalent and find the drug release mechanism?"*
>
> **Agent Action**:
> 1. Calls `pharma_dissolution_similarity_f1_f2` with innovator `[20, 42, 65, 82, 95]` and test `[19, 40, 67, 83, 94]`.
> - **Result**: $f_1 = 3.12$ (Pass $\le 15$), $f_2 = 82.45$ (Pass $\ge 50$) $\rightarrow$ **Bioequivalent per FDA/EMA criteria**.
> 2. Calls `pharma_fit_release_kinetics` with times `[0.5, 1, 2, 4, 8]` and release percentages.
> - **Result**: Fits Higuchi ($R^2 = 0.991$) and Korsmeyer-Peppas ($n = 0.48$) $\rightarrow$ **Non-Fickian anomalous diffusion**.
---
### ๐ฉบ Scenario 2: Preclinical In-Vivo Animal Study Design
> **User**: *"We are writing an animal protocol for testing our novel formulation in diabetic rats against Metformin. What sample size do we need, and what are the ethical considerations?"*
>
> **Agent Action**:
> 1. Calls `pharma_sample_size_calculator` with $\alpha = 0.05, \text{Power} = 0.80, d = 0.80$.
> - **Result**: Minimum $n = 26$ per group; recommended $n = 29$ with 10% attrition buffer.
> 2. Provides ready-to-paste justification snippet for CPCSEA / IACUC ethics approval.
---
### ๐ Scenario 3: Cytotoxicity IC50 & Dose-Response Determination
> **User**: *"Here is our MTT assay data for compound X against MCF-7 breast cancer cells at 0.01, 0.1, 1, 10, 100 uM: [98.5, 84.1, 52.3, 16.4, 2.1]. Compute the IC50."*
>
> **Agent Action**:
> 1. Calls `pharma_fit_ic50_ec50`.
> - **Result**: $IC_{50} = 1.05\ \mu\text{M}$ ($pIC_{50} = 5.98$, 95% CI: $0.92\text{--}1.21\ \mu\text{M}$, $R^2 = 0.999$).
---
## ๐ Project Structure
```
pharma-mcp/
โโโ server.py # FastMCP entrypoint & tool registrations
โโโ requirements.txt # Python dependencies
โโโ LICENSE # MIT License
โโโ README.md # Project documentation
โโโ claude_desktop_config_snippet.json # Ready-to-copy MCP client configuration
โโโ modules/ # Domain engines
โ โโโ __init__.py
โ โโโ literature.py # PubMed, ClinicalTrials, DOI, PDF parsing
โ โโโ chemistry.py # PubChem, Lipinski, buffer formulations
โ โโโ pharmacology.py # DDI check, PK equations, ADMET rules
โ โโโ pharmaceutics.py # f1/f2, dissolution models, Henderson-Hasselbalch
โ โโโ statistics.py # t-test, ANOVA, 4PL IC50, power sample size
โ โโโ writing.py # Vancouver/APA citations, IMRaD review
โโโ tests/ # Automated test suite
โโโ __init__.py
โโโ test_modules.py # 18 unit and integration tests
```
---
## ๐ค Contributing
Contributions are welcomed from pharmacists, chemists, pharmacologists, and developers!
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/NewPharmaTool`)
3. Commit your changes (`git commit -m 'Add new bioanalytical tool'`)
4. Push to the branch (`git push origin feature/NewPharmaTool`)
5. Open a Pull Request
---
## ๐ License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues