tokencost-mcp-server

Instructions

Implementation Reference

• src/index.ts:216-260 (handler)

  The handler function for tokencost_estimate_cost tool. Looks up the model using findModel(), calculates input/output costs based on token counts and pricing rates, and returns formatted markdown text and structured JSON content with cost breakdown.

  async ({ model, input_tokens, output_tokens }) => {
    const found = findModel(model);
    if (!found) {
      return {
        content: [{ type: "text", text: `Model "${model}" not found. Use tokencost_list_models to see available models.` }],
      };
    }
  
    const inputCost = (input_tokens / 1_000_000) * found.inputPer1M;
    const outputCost = (output_tokens / 1_000_000) * found.outputPer1M;
    const totalCost = inputCost + outputCost;
  
    const text = [
      `# Cost Estimate: ${found.name}`,
      "",
      `| | Tokens | Cost |`,
      `|---|--------|------|`,
      `| Input | ${input_tokens.toLocaleString()} | ${formatUSD(inputCost)} |`,
      `| Output | ${output_tokens.toLocaleString()} | ${formatUSD(outputCost)} |`,
      `| **Total** | **${(input_tokens + output_tokens).toLocaleString()}** | **${formatUSD(totalCost)}** |`,
      "",
      `*Rates: $${found.inputPer1M}/1M input, $${found.outputPer1M}/1M output*`,
      `*Calculate more at [TokenCost](https://tokencost.app)*`,
    ].join("\n");
  
    const structured = {
      model: found.id,
      model_name: found.name,
      provider: found.provider,
      input_tokens,
      output_tokens,
      input_cost_usd: inputCost,
      output_cost_usd: outputCost,
      total_cost_usd: totalCost,
      rates: {
        input_per_1m: found.inputPer1M,
        output_per_1m: found.outputPer1M,
      },
    };
  
    return {
      content: [{ type: "text", text }],
      structuredContent: structured,
    };
  }

• src/index.ts:204-208 (schema)

  Input schema for tokencost_estimate_cost using Zod validation. Defines three parameters: model (string, min 1 char), input_tokens (integer, 0-100B), and output_tokens (integer, 0-100B).

  inputSchema: {
    model: z.string().min(1).describe("Model ID or name"),
    input_tokens: z.number().int().min(0).max(100_000_000_000).describe("Number of input tokens"),
    output_tokens: z.number().int().min(0).max(100_000_000_000).describe("Number of output tokens"),
  },

• src/index.ts:187-261 (registration)

  Complete tool registration for tokencost_estimate_cost using server.registerTool(). Includes title, description, inputSchema, annotations, and handler function.

  server.registerTool(
    "tokencost_estimate_cost",
    {
      title: "Estimate Token Cost",
      description: `Calculate the cost for a specific number of input and output tokens with a given model.
  
  Args:
    - model (string): Model ID or name
    - input_tokens (number): Number of input tokens (0 to 100B)
    - output_tokens (number): Number of output tokens (0 to 100B)
  
  Returns:
    Cost breakdown with input cost, output cost, and total cost in USD.
  
  Examples:
    - model="gpt-5", input_tokens=1000, output_tokens=500 → Cost for a typical API call
    - model="claude-sonnet-4.6", input_tokens=100000, output_tokens=4000 → Cost for a long context call`,
      inputSchema: {
        model: z.string().min(1).describe("Model ID or name"),
        input_tokens: z.number().int().min(0).max(100_000_000_000).describe("Number of input tokens"),
        output_tokens: z.number().int().min(0).max(100_000_000_000).describe("Number of output tokens"),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ model, input_tokens, output_tokens }) => {
      const found = findModel(model);
      if (!found) {
        return {
          content: [{ type: "text", text: `Model "${model}" not found. Use tokencost_list_models to see available models.` }],
        };
      }
  
      const inputCost = (input_tokens / 1_000_000) * found.inputPer1M;
      const outputCost = (output_tokens / 1_000_000) * found.outputPer1M;
      const totalCost = inputCost + outputCost;
  
      const text = [
        `# Cost Estimate: ${found.name}`,
        "",
        `| | Tokens | Cost |`,
        `|---|--------|------|`,
        `| Input | ${input_tokens.toLocaleString()} | ${formatUSD(inputCost)} |`,
        `| Output | ${output_tokens.toLocaleString()} | ${formatUSD(outputCost)} |`,
        `| **Total** | **${(input_tokens + output_tokens).toLocaleString()}** | **${formatUSD(totalCost)}** |`,
        "",
        `*Rates: $${found.inputPer1M}/1M input, $${found.outputPer1M}/1M output*`,
        `*Calculate more at [TokenCost](https://tokencost.app)*`,
      ].join("\n");
  
      const structured = {
        model: found.id,
        model_name: found.name,
        provider: found.provider,
        input_tokens,
        output_tokens,
        input_cost_usd: inputCost,
        output_cost_usd: outputCost,
        total_cost_usd: totalCost,
        rates: {
          input_per_1m: found.inputPer1M,
          output_per_1m: found.outputPer1M,
        },
      };
  
      return {
        content: [{ type: "text", text }],
        structuredContent: structured,
      };
    }
  );

• src/index.ts:23-28 (helper)

  formatUSD helper function used by the handler to format cost values in USD with appropriate precision based on amount magnitude.

  function formatUSD(amount: number): string {
    if (amount < 0.0001) return "< $0.0001";
    if (amount < 0.01) return `$${amount.toFixed(4)}`;
    if (amount < 1) return `$${amount.toFixed(3)}`;
    return `$${amount.toFixed(2)}`;
  }

• src/pricing.ts:106-110 (helper)

  findModel function used by the handler to look up model pricing data by ID or name, with fuzzy matching fallback.

  export function findModel(query: string): ModelPricing | undefined {
    const q = query.toLowerCase();
    return models.find(m => m.id === q || m.name.toLowerCase() === q) ??
      models.find(m => m.id.includes(q) || m.name.toLowerCase().includes(q));
  }