ChEMBL MCP Server

Instructions

Implementation Reference

• src/index.ts:909-933 (handler)

  The main handler function that implements the tool logic. Fetches compound data from the ChEMBL API using the provided ChEMBL ID and returns the structure information (SMILES, InChI, etc.) in a standardized JSON response.
  private async handleGetCompoundStructure(args: any) { if (!args || typeof args.chembl_id !== 'string') { throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments'); } try { const response = await this.apiClient.get(`/molecule/${args.chembl_id}.json`); const compound = response.data; return { content: [ { type: 'text', text: JSON.stringify({ chembl_id: compound.molecule_chembl_id, structures: compound.molecule_structures || {}, requested_format: args.format || 'smiles' }, null, 2), }, ], }; } catch (error) { throw new McpError(ErrorCode.InternalError, `Failed to get structure: ${error instanceof Error ? error.message : 'Unknown error'}`); } }
• src/index.ts:433-443 (schema)

  The input schema definition for the get_compound_structure tool, specifying the required chembl_id parameter and optional format.
  name: 'get_compound_structure', description: 'Retrieve chemical structure information in various formats', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, format: { type: 'string', enum: ['smiles', 'inchi', 'molfile', 'sdf'], description: 'Structure format (default: smiles)' }, }, required: ['chembl_id'], }, },
• src/index.ts:751-753 (registration)

  The dispatch case in the CallToolRequestSchema handler that routes tool calls named 'get_compound_structure' to its handler function.
  case 'get_compound_structure': return await this.handleGetCompoundStructure(args); case 'search_similar_compounds':
• src/index.ts:394-736 (registration)

  The tool is registered in the ListToolsRequestSchema response, making it discoverable by MCP clients.
  tools: [ // Core Chemical Search & Retrieval (5 tools) { name: 'search_compounds', description: 'Search ChEMBL database for compounds by name, synonym, or identifier', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query (compound name, synonym, or identifier)' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, offset: { type: 'number', description: 'Number of results to skip (default: 0)', minimum: 0 }, }, required: ['query'], }, }, { name: 'get_compound_info', description: 'Get detailed information for a specific compound by ChEMBL ID', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID (e.g., CHEMBL59)' }, }, required: ['chembl_id'], }, }, { name: 'search_by_inchi', description: 'Search for compounds by InChI key or InChI string', inputSchema: { type: 'object', properties: { inchi: { type: 'string', description: 'InChI key or InChI string' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['inchi'], }, }, { name: 'get_compound_structure', description: 'Retrieve chemical structure information in various formats', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, format: { type: 'string', enum: ['smiles', 'inchi', 'molfile', 'sdf'], description: 'Structure format (default: smiles)' }, }, required: ['chembl_id'], }, }, { name: 'search_similar_compounds', description: 'Find chemically similar compounds using Tanimoto similarity', inputSchema: { type: 'object', properties: { smiles: { type: 'string', description: 'SMILES string of the query molecule' }, similarity: { type: 'number', description: 'Similarity threshold (0-1, default: 0.7)', minimum: 0, maximum: 1 }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['smiles'], }, }, // Target Analysis & Drug Discovery (5 tools) { name: 'search_targets', description: 'Search for biological targets by name or type', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Target name or search query' }, target_type: { type: 'string', description: 'Target type filter (e.g., SINGLE PROTEIN, PROTEIN COMPLEX)' }, organism: { type: 'string', description: 'Organism filter' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['query'], }, }, { name: 'get_target_info', description: 'Get detailed information for a specific target by ChEMBL target ID', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL target ID (e.g., CHEMBL2095173)' }, }, required: ['chembl_id'], }, }, { name: 'get_target_compounds', description: 'Get compounds tested against a specific target', inputSchema: { type: 'object', properties: { target_chembl_id: { type: 'string', description: 'ChEMBL target ID' }, activity_type: { type: 'string', description: 'Activity type filter (e.g., IC50, Ki, Kd)' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['target_chembl_id'], }, }, { name: 'search_by_uniprot', description: 'Find ChEMBL targets by UniProt accession', inputSchema: { type: 'object', properties: { uniprot_id: { type: 'string', description: 'UniProt accession number' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['uniprot_id'], }, }, { name: 'get_target_pathways', description: 'Get biological pathways associated with a target', inputSchema: { type: 'object', properties: { target_chembl_id: { type: 'string', description: 'ChEMBL target ID' }, }, required: ['target_chembl_id'], }, }, // Bioactivity & Assay Data (5 tools) { name: 'search_activities', description: 'Search bioactivity measurements and assay results', inputSchema: { type: 'object', properties: { target_chembl_id: { type: 'string', description: 'ChEMBL target ID filter' }, assay_chembl_id: { type: 'string', description: 'ChEMBL assay ID filter' }, molecule_chembl_id: { type: 'string', description: 'ChEMBL compound ID filter' }, activity_type: { type: 'string', description: 'Activity type (e.g., IC50, Ki, EC50)' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: [], }, }, { name: 'get_assay_info', description: 'Get detailed information for a specific assay by ChEMBL assay ID', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL assay ID (e.g., CHEMBL1217643)' }, }, required: ['chembl_id'], }, }, { name: 'search_by_activity_type', description: 'Find bioactivity data by specific activity type and value range', inputSchema: { type: 'object', properties: { activity_type: { type: 'string', description: 'Activity type (e.g., IC50, Ki, EC50, Kd)' }, min_value: { type: 'number', description: 'Minimum activity value' }, max_value: { type: 'number', description: 'Maximum activity value' }, units: { type: 'string', description: 'Units filter (e.g., nM, uM)' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['activity_type'], }, }, { name: 'get_dose_response', description: 'Get dose-response data and activity profiles for compounds', inputSchema: { type: 'object', properties: { molecule_chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, target_chembl_id: { type: 'string', description: 'ChEMBL target ID (optional filter)' }, }, required: ['molecule_chembl_id'], }, }, { name: 'compare_activities', description: 'Compare bioactivity data across multiple compounds or targets', inputSchema: { type: 'object', properties: { molecule_chembl_ids: { type: 'array', items: { type: 'string' }, description: 'Array of ChEMBL compound IDs (2-10)', minItems: 2, maxItems: 10 }, target_chembl_id: { type: 'string', description: 'ChEMBL target ID for comparison' }, activity_type: { type: 'string', description: 'Activity type for comparison' }, }, required: ['molecule_chembl_ids'], }, }, // Drug Development & Clinical Data (4 tools) { name: 'search_drugs', description: 'Search for approved drugs and clinical candidates', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Drug name or search query' }, development_phase: { type: 'string', description: 'Development phase filter (e.g., Approved, Phase III)' }, therapeutic_area: { type: 'string', description: 'Therapeutic area filter' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['query'], }, }, { name: 'get_drug_info', description: 'Get drug development status and clinical trial information', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, }, required: ['chembl_id'], }, }, { name: 'search_drug_indications', description: 'Search for therapeutic indications and disease areas', inputSchema: { type: 'object', properties: { indication: { type: 'string', description: 'Disease or indication search term' }, drug_type: { type: 'string', description: 'Drug type filter (e.g., Small molecule, Antibody)' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['indication'], }, }, { name: 'get_mechanism_of_action', description: 'Get mechanism of action and target interaction data', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, }, required: ['chembl_id'], }, }, // Chemical Property Analysis (4 tools) { name: 'analyze_admet_properties', description: 'Analyze ADMET properties (Absorption, Distribution, Metabolism, Excretion, Toxicity)', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, }, required: ['chembl_id'], }, }, { name: 'calculate_descriptors', description: 'Calculate molecular descriptors and physicochemical properties', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, smiles: { type: 'string', description: 'SMILES string (alternative to ChEMBL ID)' }, }, required: [], }, }, { name: 'predict_solubility', description: 'Predict aqueous solubility and permeability properties', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, smiles: { type: 'string', description: 'SMILES string (alternative to ChEMBL ID)' }, }, required: [], }, }, { name: 'assess_drug_likeness', description: 'Assess drug-likeness using Lipinski Rule of Five and other metrics', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound ID' }, smiles: { type: 'string', description: 'SMILES string (alternative to ChEMBL ID)' }, }, required: [], }, }, // Advanced Search & Cross-References (4 tools) { name: 'substructure_search', description: 'Find compounds containing specific substructures', inputSchema: { type: 'object', properties: { smiles: { type: 'string', description: 'SMILES string of the substructure query' }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: ['smiles'], }, }, { name: 'batch_compound_lookup', description: 'Process multiple ChEMBL IDs efficiently', inputSchema: { type: 'object', properties: { chembl_ids: { type: 'array', items: { type: 'string' }, description: 'Array of ChEMBL compound IDs (1-50)', minItems: 1, maxItems: 50 }, }, required: ['chembl_ids'], }, }, { name: 'get_external_references', description: 'Get links to external databases (PubChem, DrugBank, PDB, etc.)', inputSchema: { type: 'object', properties: { chembl_id: { type: 'string', description: 'ChEMBL compound or target ID' }, }, required: ['chembl_id'], }, }, { name: 'advanced_search', description: 'Complex queries with multiple chemical and biological filters', inputSchema: { type: 'object', properties: { min_mw: { type: 'number', description: 'Minimum molecular weight (Da)', minimum: 0 }, max_mw: { type: 'number', description: 'Maximum molecular weight (Da)', minimum: 0 }, min_logp: { type: 'number', description: 'Minimum LogP value' }, max_logp: { type: 'number', description: 'Maximum LogP value' }, max_hbd: { type: 'number', description: 'Maximum hydrogen bond donors', minimum: 0 }, max_hba: { type: 'number', description: 'Maximum hydrogen bond acceptors', minimum: 0 }, limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 }, }, required: [], }, }, ],
• src/index.ts:90-98 (helper)

  Type guard function used for validating the chembl_id argument in the handler and other similar tools.
  const isValidChemblIdArgs = ( args: any ): args is { chembl_id: string } => { return ( typeof args === 'object' && args !== null && typeof args.chembl_id === 'string' && args.chembl_id.length > 0 );