PubChem MCP Server

Instructions

Implementation Reference

• src/index.ts:832-880 (handler)

  The main handler function that executes the search_compounds tool. Validates input, queries PubChem API for CIDs by name/SMILES/etc., fetches details for top results, and returns formatted JSON response.

  private async handleSearchCompounds(args: any) {
    if (!isValidCompoundSearchArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid compound search arguments');
    }
  
    try {
      const searchType = args.search_type || 'name';
      const maxRecords = args.max_records || 100;
  
      const response = await this.apiClient.get(`/compound/${searchType}/${encodeURIComponent(args.query)}/cids/JSON`, {
        params: {
          MaxRecords: maxRecords,
        },
      });
  
      if (response.data?.IdentifierList?.CID?.length > 0) {
        const cids = response.data.IdentifierList.CID.slice(0, 10);
        const detailsResponse = await this.apiClient.get(`/compound/cid/${cids.join(',')}/property/MolecularFormula,MolecularWeight,CanonicalSMILES,IUPACName/JSON`);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                query: args.query,
                search_type: searchType,
                total_found: response.data.IdentifierList.CID.length,
                details: detailsResponse.data,
              }, null, 2),
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ message: 'No compounds found', query: args.query }, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to search compounds: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:371-382 (schema)

  Tool registration entry in ListToolsRequestSchema handler, defining the tool name, description, and input schema for validation.

    name: 'search_compounds',
    description: 'Search PubChem database for compounds by name, CAS number, formula, or identifier',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query (compound name, CAS, formula, or identifier)' },
        search_type: { type: 'string', enum: ['name', 'smiles', 'inchi', 'sdf', 'cid', 'formula'], description: 'Type of search to perform (default: name)' },
        max_records: { type: 'number', description: 'Maximum number of results (1-10000, default: 100)', minimum: 1, maximum: 10000 },
      },
      required: ['query'],
    },
  },

• src/index.ts:52-63 (helper)

  Type guard function for validating input arguments to the search_compounds tool.

  const isValidCompoundSearchArgs = (
    args: any
  ): args is { query: string; search_type?: string; max_records?: number } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.query === 'string' &&
      args.query.length > 0 &&
      (args.search_type === undefined || ['name', 'smiles', 'inchi', 'sdf', 'cid', 'formula'].includes(args.search_type)) &&
      (args.max_records === undefined || (typeof args.max_records === 'number' && args.max_records > 0 && args.max_records <= 10000))
    );
  };

• src/index.ts:740-741 (registration)

  Switch case in CallToolRequestSchema handler that routes execution to the search_compounds handler function.

  case 'search_compounds':
    return await this.handleSearchCompounds(args);