Unofficial PubChem MCP Server

Instructions

Implementation Reference

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

  The main handler function that executes the search_compounds tool. Validates args, performs PubChem PUG API search by specified type (default 'name'), retrieves CIDs, fetches details for top 10 (formula, weight, SMILES, IUPAC), returns formatted JSON response or no-results message.

  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 (registration)

  Tool registration in the MCP server's ListToolsRequestSchema handler, defining the name, description, and input schema for search_compounds.

    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:373-381 (schema)

  JSON schema defining the input parameters for the search_compounds tool: required 'query' string, optional 'search_type' enum, and 'max_records' number.

  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 and validation function for search_compounds input arguments, ensuring query is non-empty string, search_type is valid enum or undefined, max_records is positive number <=10000 or undefined.

  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)

  Dispatch case in the CallToolRequestSchema switch statement that routes 'search_compounds' calls to the handleSearchCompounds method.

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