BioMedCP - Biomedical Context Protocol Server

BioMedCP is an MCP (Model Context Protocol) server that integrates electronic health record databases and a large-scale heterogeneous knowledge graph for rapid clinical record query and fast biomedical knowledge inference.

Features

• Query biomedical knowledge graphs (Neo4j) for drug-disease associations, protein interactions, pathways, and other biomedical entities
• Execute read-only queries on electronic health records (SQL Server)
• List and explore clinical data tables
• Retrieve knowledge graph schema for understanding biomedical relationships
• Secure read-only operations with query validation
• Environment variable-based configuration

Installation

npx biomedcp

Configuration

BioMedCP requires environment variables for database credentials. At least one database (knowledge graph or clinical records) must be configured.

Knowledge Graph (Neo4j) Environment Variables

• KNOWLEDGE_GRAPH_URI - Neo4j connection URI (e.g., bolt://localhost:7687 or neo4j://localhost:7687)
• KNOWLEDGE_GRAPH_USERNAME - Neo4j username
• KNOWLEDGE_GRAPH_PASSWORD - Neo4j password
• KNOWLEDGE_GRAPH_DATABASE - Neo4j database name (optional, defaults to neo4j)

Clinical Records (SQL Server) Environment Variables

• CLINICAL_RECORDS_SERVER - SQL Server host (e.g., ehr-server.hospital.org)
• CLINICAL_RECORDS_DATABASE - Database name
• CLINICAL_RECORDS_USERNAME - SQL Server username
• CLINICAL_RECORDS_PASSWORD - SQL Server password

Optional Configuration

• BIOMEDCP_NAMESPACE - Tool namespace prefix (optional, defaults to BioMedCP)
• BIOMEDCP_LOG_LEVEL - Logging level: DEBUG, INFO, WARNING, ERROR (defaults to INFO)
• CLINICAL_RECORDS_PORT - SQL Server port (optional, defaults to 1433)
• CLINICAL_RECORDS_ENCRYPT - Enable encryption (optional, defaults to true)
• CLINICAL_RECORDS_TRUST_CERT - Trust server certificate (optional, defaults to true)
• CLINICAL_RECORDS_AUTH_TYPE - Authentication type: default, ntlm, azure-active-directory-password (optional)

Important: SQL Server Authentication on macOS/Linux

Windows Domain Authentication is NOT supported on macOS or Linux. If you're on a non-Windows platform:

1. Use SQL Server Authentication (recommended):

   • Remove the domain prefix from username
   • Use: CLINICAL_RECORDS_USERNAME=username (not DOMAIN\username)
   • Ask your DBA to create a SQL Server authentication account

2. Alternative: Use a Windows machine to run the MCP server if domain authentication is required

Usage with Goose

Add BioMedCP to your Goose configuration:

extensions:
  biomedcp:
    name: BioMedCP
    cmd: npx
    args: [-y, biomedcp]
    enabled: true
    envs:
      KNOWLEDGE_GRAPH_URI: "bolt://your-neo4j-server:7687"
      KNOWLEDGE_GRAPH_USERNAME: "neo4j"
      KNOWLEDGE_GRAPH_PASSWORD: "your-password"
      KNOWLEDGE_GRAPH_DATABASE: "neo4j"
      CLINICAL_RECORDS_SERVER: "your-sql-server.com"
      CLINICAL_RECORDS_DATABASE: "EHR_Database"
      CLINICAL_RECORDS_USERNAME: "ehr_user"
      CLINICAL_RECORDS_PASSWORD: "your-password"
      BIOMEDCP_NAMESPACE: "BioMedCP"
      BIOMEDCP_LOG_LEVEL: "INFO"
    type: stdio
    timeout: 300

Goose Deeplink

Install BioMedCP via Goose deeplink (replace with your credentials):

goose://extension?cmd=npx&arg=-y&arg=biomedcp&id=biomedcp&name=BioMedCP&description=Biomedical%20knowledge%20graph%20and%20EHR%20query%20server&timeout=300

Usage with Cursor / Claude Desktop / Windsurf

Add to your MCP settings configuration file:

{
  "mcpServers": {
    "biomedcp": {
      "command": "npx",
      "args": ["-y", "biomedcp"],
      "env": {
        "KNOWLEDGE_GRAPH_URI": "bolt://your-neo4j-server:7687",
        "KNOWLEDGE_GRAPH_USERNAME": "neo4j",
        "KNOWLEDGE_GRAPH_PASSWORD": "your-password",
        "KNOWLEDGE_GRAPH_DATABASE": "neo4j",
        "CLINICAL_RECORDS_SERVER": "your-sql-server.com",
        "CLINICAL_RECORDS_DATABASE": "EHR_Database",
        "CLINICAL_RECORDS_USERNAME": "ehr_user",
        "CLINICAL_RECORDS_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Knowledge Graph Tools

get_knowledge_graph_schema

List all nodes, their attributes and their relationships in the biomedical knowledge graph. This provides the schema for drug-disease associations, protein interactions, pathways, and other biomedical entities.

Requirements: APOC plugin must be installed and enabled on Neo4j

Returns: JSON schema of the knowledge graph structure

query_knowledge_graph

Execute a read-only Cypher query on the biomedical knowledge graph for fast knowledge inference.

Parameters:

• cypher_query (string, required) - The Cypher query for biomedical knowledge inference (e.g., drug-disease associations, protein interactions)
• parameters (object, optional) - Parameters to pass to the knowledge graph query

Returns: JSON array of query results

Example:

MATCH (d:Drug)-[r:TREATS]->(disease:Disease)
WHERE disease.name = $disease_name
RETURN d.name, r.efficacy, disease.name
LIMIT 10

Clinical Records Tools

query_clinical_records

Execute a READ-ONLY SQL query on electronic health records for rapid clinical data retrieval.

Parameters:

• sql_query (string, required) - SQL SELECT query for rapid clinical record retrieval (read-only)

Returns: CSV formatted results

Security: Only SELECT, WITH, and DECLARE statements are allowed. Write operations are blocked.

Example:

SELECT patient_id, diagnosis, admission_date
FROM dbo.Admissions
WHERE admission_date >= '2024-01-01'
ORDER BY admission_date DESC

list_clinical_tables

List all available clinical data tables in the electronic health records database.

Returns: JSON array of table information including schema, table name, type, and full name

Security Features

• Read-only operations: All queries are validated to prevent write operations
• Query validation: SQL injection patterns are detected and blocked
• Parameterized queries: Support for safe parameter binding
• Secure connections: SSL/TLS encryption for database connections

Development

Local Development Setup

# Clone the repository
git clone <repository-url>
cd BioMedCP

# Install dependencies
npm install

# Build the server
npm run build

# Run the MCP inspector for testing
npm run inspector

Environment Setup

Create a .env file in the project root:

KNOWLEDGE_GRAPH_URI=bolt://localhost:7687
KNOWLEDGE_GRAPH_USERNAME=neo4j
KNOWLEDGE_GRAPH_PASSWORD=your-password
KNOWLEDGE_GRAPH_DATABASE=neo4j

CLINICAL_RECORDS_SERVER=localhost
CLINICAL_RECORDS_DATABASE=EHR_Test
CLINICAL_RECORDS_USERNAME=sa
CLINICAL_RECORDS_PASSWORD=your-password

BIOMEDCP_NAMESPACE=BioMedCP
BIOMEDCP_LOG_LEVEL=DEBUG

Run Locally in MCP Client

For local development with Cursor / Claude Desktop / Windsurf:

{
  "mcpServers": {
    "biomedcp": {
      "command": "node",
      "args": ["/absolute/path/to/BioMedCP/build/index.js"],
      "env": {
        "KNOWLEDGE_GRAPH_URI": "bolt://localhost:7687",
        "KNOWLEDGE_GRAPH_USERNAME": "neo4j",
        "KNOWLEDGE_GRAPH_PASSWORD": "your-password"
      }
    }
  }
}

Note: For Windows, the args path needs to be C:\\absolute\\path\\to\\BioMedCP\\build\\index.js

Requirements

• Node.js 18 or higher
• Neo4j database with APOC plugin (for knowledge graph features)
• SQL Server database (for clinical records features)

License

MIT

Related Projects

• MedCP - Python version of this MCP server
• Model Context Protocol - MCP specification and SDK

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on the GitHub repository.