# Biomedical APIs MCP Server

This Model Context Protocol (MCP) server exposes **14 tools** to query free biomedical and pharmaceutical APIs—plus stubs for restricted/paid sources—enabling AI agents to access clinical trial data, drug information, molecular structures, adverse events, and research literature.

---

## 🎯 Available APIs

### **Free & Open APIs** (fully functional)
1. **ClinicalTrials.gov** → Search registered clinical trials worldwide
2. **ChEMBL** → Small molecules, bioactivity data, drug-like compounds
3. **PubChem** → Chemical compounds, molecular properties
4. **OpenFDA** → FDA adverse event reports (drug, device, food)
5. **Europe PMC** → Biomedical research articles and preprints

### **Restricted/Paid APIs** (stubs only)
6. **dbGaP** → NIH genomic & clinical datasets (requires NIH credentials)
7. **PhysioNet** → Physiological signals (requires credentialed access)
8. **MIMIC-IV** → ICU records (PhysioNet credential + CITI training)
9. **UK Biobank** → Large-scale biomedical data (application required)
10. **DrugBank** → Structured drug data (academic/commercial license)
11. **BindingDB** → Protein-ligand binding affinities (bulk download)
12. **OpenTrials** → Merged trial data & sponsors (open access)
13. **Crunchbase** → Company & funding data (free tier limited)

---

## 🚀 Quick Start

### 1. Install Dependencies
```bash
npm install
```

### 2. Configure Environment (optional)
Copy `.env.example` to `.env` and add optional API keys:
```bash
cp .env.example .env
```
Edit `.env`:
```env
OPENFDA_API_KEY=your_key_here  # Optional: increases OpenFDA rate limits
CRUNCHBASE_API_KEY=your_key_here  # Optional: enables Crunchbase free tier
```

### 3. Build the Server
```bash
npm run build
```

### 4. Run in Development Mode
```bash
npm run dev
```

### 5. Use in Production
```bash
npm start
```

---

## 🧪 Testing with MCP Inspector

[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) lets you test your server interactively:

```bash
npx @modelcontextprotocol/inspector node dist/server.js
```

Once connected, you can:
- List all 14 available tools
- Test tool calls with custom inputs
- View structured JSON responses
- Debug errors and API rate limits

---

## 🔌 Connecting to Clients

### **VS Code (Copilot Agent Mode)**

The server is pre-configured in `.vscode/mcp.json`:

```json
{
  "servers": {
    "biomed-apis": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}
```

To connect:
1. Open this workspace in VS Code
2. Restart VS Code (if needed)
3. Open Copilot Chat and confirm the MCP server is listed
4. Ask: *"Search ClinicalTrials.gov for epilepsy trials started in 2023"*

### **Claude Desktop**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "biomed-apis": {
      "command": "node",
      "args": ["C:\\For Me\\Projects\\mcp with DBs\\dist\\server.js"]
    }
  }
}
```

Restart Claude Desktop. The tools will appear in the MCP panel.

### **Claude Code CLI**

```bash
claude mcp add --transport stdio biomed-apis node "C:\\For Me\\Projects\\mcp with DBs\\dist\\server.js"
```

---

## 📚 Example Tool Calls

### 1. **Search Clinical Trials**
```json
{
  "tool": "search_clinical_trials",
  "input": {
    "query": "epilepsy",
    "filter": "AREA[StartDate]2020-01-01+TO+2023-12-31",
    "pageSize": 5
  }
}
```
**Returns:** NCT IDs, titles, status, phases, conditions, interventions

---

### 2. **Search ChEMBL Compounds**
```json
{
  "tool": "search_chembl_compounds",
  "input": {
    "query": "aspirin",
    "limit": 5
  }
}
```
**Returns:** ChEMBL IDs, molecular formulas, weights, max clinical phase

---

### 3. **Get ChEMBL Bioactivity Data**
```json
{
  "tool": "get_chembl_activities",
  "input": {
    "targetChemblId": "CHEMBL2",
    "limit": 10
  }
}
```
**Returns:** Activity IDs, assay IDs, molecules, types (IC50, Ki, etc.), values, units

---

### 4. **Get PubChem Compound by Name**
```json
{
  "tool": "get_pubchem_compound",
  "input": {
    "name": "glucose"
  }
}
```
**Returns:** CID, molecular formula, weight, IUPAC name, SMILES

---

### 5. **Search OpenFDA Drug Adverse Events**
```json
{
  "tool": "search_openfda_drug_events",
  "input": {
    "search": "patient.drug.medicinalproduct:\"metformin\"",
    "limit": 10
  }
}
```
**Returns:** Receive dates, patient ages, reactions, drug names

---

### 6. **Search Europe PMC Articles**
```json
{
  "tool": "search_europepmc_articles",
  "input": {
    "query": "CRISPR gene editing",
    "pageSize": 10
  }
}
```
**Returns:** Article IDs, sources, titles, authors, journals, publication years

---

### 7. **Query Restricted APIs (Stubs)**
```json
{
  "tool": "query_dbgap",
  "input": {
    "query": "GWAS cardiovascular disease"
  }
}
```
**Returns:** `[dbGaP stub] Querying: "GWAS cardiovascular disease". Access requires NIH credentials & dbGaP approval.`

> **Note:** Stubs for dbGaP, PhysioNet, MIMIC-IV, UK Biobank, DrugBank, BindingDB, OpenTrials, and Crunchbase return informational messages. Replace the stub functions in `src/clients/restrictedStubs.ts` with real implementations once you have credentials.

---

## 🛠️ Project Structure

```
mcp-biomed-server/
├── src/
│   ├── server.ts                    # Main MCP server with all 14 tools
│   └── clients/
│       ├── clinicalTrialsClient.ts  # ClinicalTrials.gov
│       ├── chemblClient.ts          # ChEMBL
│       ├── pubchemClient.ts         # PubChem
│       ├── openfdaClient.ts         # OpenFDA
│       ├── europePmcClient.ts       # Europe PMC
│       └── restrictedStubs.ts       # Stubs for restricted APIs
├── dist/                            # Compiled JavaScript (after build)
├── .vscode/
│   └── mcp.json                     # VS Code MCP config
├── .env.example                     # Environment variable template
├── package.json
├── tsconfig.json
└── README.md
```

---

## 🔧 Development

### **Adding a New Tool**

1. **Create a client function** in `src/clients/` (or add to existing file)
2. **Register the tool** in `src/server.ts`:
   ```typescript
   server.registerTool(
     'my_tool_name',
     {
       title: 'My Tool',
       description: 'What it does',
       inputSchema: { param: z.string().describe('Parameter description') },
       outputSchema: { result: z.string() }
     },
     async ({ param }) => {
       const result = await myClientFunction(param);
       return {
         content: [{ type: 'text', text: JSON.stringify({ result }) }],
         structuredContent: { result }
       };
     }
   );
   ```
3. **Rebuild**: `npm run build`

### **Debugging**

- Use `npm run dev` for live TypeScript execution via `tsx`
- Server logs errors to `stderr` (visible in MCP Inspector or client logs)
- Check rate limits if APIs return HTTP 429

---

## ⚖️ Rate Limits & Best Practices

| API | Rate Limit | Notes |
|-----|-----------|-------|
| **ClinicalTrials.gov** | ~1000 req/day | No key required; public access |
| **ChEMBL** | Unknown (generous) | No key; community-supported |
| **PubChem** | ~5 req/sec | No key; use delays for bulk requests |
| **OpenFDA** | 240 req/min (1000/day without key) | API key increases to 240 req/min |
| **Europe PMC** | Unknown (generous) | No key; rate-limited |

**Tips:**
- Use `pageSize`/`limit` parameters to control result counts
- Add exponential backoff for HTTP 429 errors
- Consider caching responses for repeated queries

---

## 📖 References

- [Model Context Protocol Docs](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [ClinicalTrials.gov API](https://clinicaltrials.gov/data-api/api)
- [ChEMBL API](https://www.ebi.ac.uk/chembl/api/data/docs)
- [PubChem PUG REST](https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest)
- [OpenFDA API](https://open.fda.gov/apis/)
- [Europe PMC API](https://europepmc.org/RestfulWebService)

---

## 📝 License

MIT (adjust as needed for your project)

---

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/new-api`)
3. Add your client in `src/clients/`
4. Register tools in `src/server.ts`
5. Test with MCP Inspector
6. Submit a pull request

---

## 🐛 Troubleshooting

### **"Cannot find module" errors**
```bash
npm install  # Reinstall dependencies
npm run build  # Rebuild after changes
```

### **VS Code doesn't recognize the MCP server**
1. Ensure `.vscode/mcp.json` exists
2. Rebuild: `npm run build`
3. Restart VS Code
4. Check VS Code's MCP output panel for errors

### **API returns 429 (Too Many Requests)**
- Add delays between requests
- Use optional API keys (OpenFDA, Crunchbase)
- Reduce `pageSize`/`limit` parameters

### **Stub tools return placeholder messages**
- This is expected! Restricted APIs require credentials
- Replace functions in `src/clients/restrictedStubs.ts` with real implementations

---

## 🎉 Next Steps

- **Test all 14 tools** with MCP Inspector
- **Connect to VS Code Copilot** and try example queries
- **Replace stubs** with real API implementations (if you have access)
- **Add rate limiting** and caching for production use
- **Extend with more APIs**: BindingDB real download, OpenTrials integration, etc.

---

**Built with 💙 using [Model Context Protocol](https://modelcontextprotocol.io/)**