Alchemy MCP Server

Implementation Reference

• api/alchemyApi.ts:123-136 (handler)

  Core handler function that executes the API call to Alchemy's NFT endpoint to fetch NFTs owned by the given multichain addresses.

  async getNftsForAddress(params: NftsByAddressParams) {
    try {
      const client = createNftClient();
      
      const response = await client.post('/by-address', { 
        ...params
      });
  
      return response.data;
    } catch (error) {
      console.error('Error fetching NFTs for address:', error);
      throw error;
    }
  },

• index.ts:253-283 (registration)

  Tool registration including Zod input schema validation and inline wrapper handler that calls the core alchemyApi handler and formats response.

  server.tool('fetchNftsOwnedByMultichainAddresses', {
    addresses: z.array(z.object({
      address: z.string().describe('The wallet address to query. e.g. "0x1234567890123456789012345678901234567890"'),
      networks: z.array(z.string()).default(['eth-mainnet']).describe('The blockchain networks to query. e.g. ["eth-mainnet", "base-mainnet"]'),
      excludeFilters: z.array(z.enum(['SPAM', 'AIRDROPS'])).default(["SPAM", "AIRDROPS"]).describe('The filters to exclude from the results. e.g. ["SPAM", "AIRDROPS"]'),
      includeFilters: z.array(z.enum(['SPAM', 'AIRDROPS'])).default([]).describe('The filters to include in the results. e.g. ["SPAM", "AIRDROPS"]'),
      spamConfidenceLevel: z.enum(['LOW', 'MEDIUM', 'HIGH', 'VERY_HIGH']).default('VERY_HIGH').describe('The spam confidence level to query. e.g. "LOW" or "HIGH"'),
    })).describe('A list of wallet address and network pairs'),
    withMetadata: z.boolean().default(true).describe('Whether to include metadata in the results.'),
    pageKey: z.string().optional().describe('The cursor to start the search from. Use this to paginate through the results.'),
    pageSize: z.number().default(10).describe('The number of results to return. Default is 100. Max is 100'),
  }, async (params) => {
    try {
      const result = await alchemyApi.getNftsForAddress(params);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      if (error instanceof Error) {
        console.error('Error in getNFTsForOwner:', error);
        return {
          content: [{ type: "text", text: `Error: ${error.message}` }],
          isError: true
        };
      }
      return {
        content: [{ type: "text", text: 'Unknown error occurred' }],
        isError: true
      };
    }
  });

• types/types.d.ts:51-64 (schema)

  TypeScript type definitions for the input parameters of the NFT fetch tool, matching the Zod schema.

  export interface NftsByAddressParams {
    addresses: NftsByAddressPair[];
    withMetadata: boolean;
    pageKey?: string;
    pageSize: number;
  }
  
  export interface NftsByAddressPair {
    address: string;
    networks: string[];
    excludeFilters: Array<'SPAM' | 'AIRDROPS'>;
    includeFilters: Array<'SPAM' | 'AIRDROPS'>;
    spamConfidenceLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'VERY_HIGH';
  }

• api/alchemyClients.ts:61-68 (helper)

  Helper function that creates the Axios HTTP client configured for Alchemy's NFT API endpoint.

  export const createNftClient = () => axios.create({
    baseURL: `https://api.g.alchemy.com/data/v1/${API_KEY}/assets/nfts`,
    headers: {
        'accept': 'application/json',
        'content-type': 'application/json',
        'x-alchemy-client-breadcrumb': BREADCRUMB_HEADER
    },
  });