Token Metrics MCP Server

Instructions

Implementation Reference

• src/tools/token-data.ts:78-89 (handler)

  The performApiRequest method, specific to TokenDataTool, implements the tool logic by preparing parameters and calling the Token Metrics API at /tokens endpoint.

    protected async performApiRequest(
      input: TokenDataInput,
    ): Promise<TokenMetricsResponse> {
      this.validateApiKey();
      const params = this.buildParams(input);
  
      return (await this.makeApiRequest(
        "/tokens",
        params,
      )) as TokenMetricsResponse;
    }
  }

• src/tools/token-data.ts:26-76 (schema)

  The getToolDefinition method defines the tool's name, description, and input schema for validation.

  getToolDefinition(): Tool {
    return {
      name: "get_tokens_data",
      description:
        "Fetch token(s) data from Token Metrics API. Provide either token_id or symbol (or both) along with optional date range.",
      inputSchema: {
        type: "object",
        properties: {
          token_id: {
            type: "string",
            description: "Comma-separated string of token IDs (e.g., '1,2,3')",
          },
          token_name: {
            type: "string",
            description:
              "Comma Separated Crypto Asset Names (e.g., Bitcoin, Ethereum)",
          },
          symbol: {
            type: "string",
            description:
              "Comma-separated string of token symbols (e.g., 'BTC,ETH,ADA')",
          },
          category: {
            type: "string",
            description:
              "Comma Separated category name. Example: yield farming,defi",
          },
          exchange: {
            type: "string",
            description: "Comma Separated exchange name. Example: binance,gate",
          },
          blockchain_address: {
            type: "string",
            description:
              "Use this parameter to search tokens through specific blockchains and contract addresses. Input the blockchain name followed by a colon and then the contract address. Example: binance-smart-chain:0x57185189118c7e786cafd5c71f35b16012fa95ad",
          },
          limit: {
            type: "number",
            description:
              "Limit the number of results returned. Default is 50. Maximum is 100.",
          },
          page: {
            type: "number",
            description:
              "Enables pagination and data retrieval control by skipping a specified number of items before fetching data. Page should be a non-negative integer, with 1 indicating the beginning of the dataset.",
          },
        },
        required: [],
      },
    } as Tool;
  }

• src/tools/index.ts:28-53 (registration)

  Instantiation and registration of TokenDataTool in the central AVAILABLE_TOOLS array, which is likely used by the MCP server.

  // Registry of all available tools
  export const AVAILABLE_TOOLS: BaseTool[] = [
    new TokenDataTool(),
    new PriceTool(),
    new HourlyOHLCVTool(),
    new DailyOHLCVTool(),
    new TokenInvestorGradeTool(),
    new MarketMetricsTool(),
    new TokenTradingSignalTool(),
    new AiReportTool(),
    new CryptoInvestorTool(),
    new TopTokensTool(),
    new ResistanceSupportTool(),
    new SentimentTool(),
    new QuantMetricsTool(),
    new ScenarioAnalysisTool(),
    new CorrelationTool(),
    new IndicesTool(),
    new IndicesHoldingsTool(),
    new IndicesPerformanceTool(),
    new TokenHourlyTradingSignalTool(),
    new MoonshotTokensTool(),
    new TokenTmGradeTool(),
    new TokenTmGradeHistoricalTool(),
    new TokenTechnologyGradeTool(),
  ];

• src/tools/base-api-tool.ts:21-45 (handler)

  The execute method from the base class, called when the tool is invoked, handles API call execution and response formatting.

  async execute(args: any): Promise<ToolResponse> {
    try {
      const result = await this.performApiRequest(args);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching data: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/base-api-tool.ts:62-100 (helper)

  The makeApiRequest helper performs the HTTP request to the Token Metrics API using axios, with authentication and comprehensive error handling.

  protected async makeApiRequest(
    endpoint: string,
    params: Record<string, string | number>,
  ): Promise<TokenMetricsBaseResponse> {
    try {
      const response = await axios.get(`${this.apiBaseUrl}${endpoint}`, {
        params,
        headers: {
          Accept: "application/json",
          "x-api-key": this.apiKey,
          "x-integration": "mcp",
        },
        timeout: 30000,
      });
  
      return response.data as TokenMetricsBaseResponse;
    } catch (error) {
      console.error(`[ERROR] API request failed:`, error);
  
      if (axios.isAxiosError(error)) {
        if (error.response) {
          const errorMsg = `API Error (${
            error.response.status
          }): ${JSON.stringify(error.response.data)}`;
          console.error(`[ERROR] ${errorMsg}`);
          throw new Error(errorMsg);
        } else if (error.request) {
          const errorMsg = "Network error: Unable to reach Token Metrics API";
          console.error(`[ERROR] ${errorMsg}`);
          throw new Error(errorMsg);
        }
      }
      const errorMsg = `Request failed: ${
        error instanceof Error ? error.message : String(error)
      }`;
      console.error(`[ERROR] ${errorMsg}`);
      throw new Error(errorMsg);
    }
  }