Skip to main content
Glama
enesjakozh
yamato-snow

FastMCP

by yamato-snow
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

FastMCP

FastMCP es un marco de TypeScript para crear servidores MCP con gestión de sesiones de cliente.

[!NOTA]

Para una implementación de Python, consulte FastMCP Python .

Características principales

FastMCP ofrece las siguientes características:

Related MCP server: MCPKit

Cómo instalar

npm install fastmcp

Inicio rápido

[!NOTA]

Hay muchos casos de uso reales para FastMCP. Por favor vea el estudio de caso .

import { FastMCP } from "fastmcp";
import { z } from "zod"; // または他の検証ライブラリ（Standard Schemaをサポートしているもの）

const server = new FastMCP({
  name: "マイサーバー",
  version: "1.0.0",
});

server.addTool({
  name: "add",
  description: "2つの数値を足し算します",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

server.start({
  transportType: "stdio",
});

¡Ahora tienes un servidor MCP en funcionamiento!

Puedes probarlo en la terminal con:

git clone https://github.com/punkpeye/fastmcp.git
cd fastmcp

pnpm install
pnpm build

# CLIを使った足し算サーバーの例をテスト：
npx fastmcp dev src/examples/addition.ts
# MCP Inspectorを使った足し算サーバーの例を検査：
npx fastmcp inspect src/examples/addition.ts

SSE

Los eventos enviados por el servidor (SSE) son un mecanismo mediante el cual un servidor envía actualizaciones en tiempo real a un cliente a través de una conexión HTTPS. En MCP, SSE se utiliza principalmente para habilitar la comunicación remota de MCP, lo que permite acceder a un MCP alojado en una máquina remota y transmitir actualizaciones a través de la red.

También puedes ejecutar el servidor con soporte SSE:

server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse",
    port: 8080,
  },
});

Esto iniciará un servidor que escuchará conexiones SSE en http://localhost:8080/sse .

Luego puedes conectarte al servidor usando SSEClientTransport :

import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));

await client.connect(transport);

Conceptos básicos

herramienta

En las herramientas MCP, los servidores exponen funciones ejecutables que los clientes y LLM pueden llamar para realizar acciones.

FastMCP utiliza la especificación del esquema estándar para definir los parámetros de la herramienta. Esto le permite utilizar su biblioteca de validación de esquema favorita que implementa la especificación, como Zod, ArkType o Valibot.

Ejemplo de Zod:

import { z } from "zod";

server.addTool({
  name: "fetch-zod",
  description: "URLのコンテンツを取得します（Zodを使用）",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Ejemplo de ArkType:

import { type } from "arktype";

server.addTool({
  name: "fetch-arktype",
  description: "URLのコンテンツを取得します（ArkTypeを使用）",
  parameters: type({
    url: "string",
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Ejemplo de Valibot:

Valibot requiere una dependencia de pares: @valibot/to-json-schema.

import * as v from "valibot";

server.addTool({
  name: "fetch-valibot",
  description: "URLのコンテンツを取得します（Valibotを使用）",
  parameters: v.object({
    url: v.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Devolviendo una cadena

execute puede devolver una cadena:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return "こんにちは、世界！";
  },
});

Esto es equivalente a:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "text",
          text: "こんにちは、世界！",
        },
      ],
    };
  },
});

Devolver una lista

Si desea devolver una lista de mensajes, puede devolver un objeto con content :

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        { type: "text", text: "1つ目のメッセージ" },
        { type: "text", text: "2つ目のメッセージ" },
      ],
    };
  },
});

Devolviendo las imágenes

Para crear un objeto de contenido de imagen, utilice imageContent :

import { imageContent } from "fastmcp";

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return imageContent({
      url: "https://example.com/image.png",
    });

    // または...
    // return imageContent({
    //   path: "/path/to/image.png",
    // });

    // または...
    // return imageContent({
    //   buffer: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64"),
    // });

    // または...
    // return {
    //   content: [
    //     await imageContent(...)
    //   ],
    // };
  },
});

La función imageContent acepta las siguientes opciones:

  • url : URL de la imagen

  • path : Ruta al archivo de imagen

  • buffer : Datos de imagen como buffer

Se debe especificar exactamente uno de los siguientes: url , path o buffer .

El ejemplo anterior es equivalente a:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "image",
          data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
          mimeType: "image/png",
        },
      ],
    };
  },
});

Explotación florestal

Las herramientas pueden registrar mensajes al cliente utilizando el log del objeto de contexto:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { log }) => {
    log.info("ファイルをダウンロード中...", {
      url: args.url,
    });

    // ...

    log.info("ファイルをダウンロードしました");

    return "完了";
  },
});

log tiene los siguientes métodos:

  • debug(message: string, data?: SerializableValue)

  • error(message: string, data?: SerializableValue)

  • info(message: string, data?: SerializableValue)

  • warn(message: string, data?: SerializableValue)

error

Los errores que deben mostrarse al usuario deben generarse como instancias UserError :

import { UserError } from "fastmcp";

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    if (args.url.startsWith("https://example.com")) {
      throw new UserError("このURLは許可されていません");
    }

    return "完了";
  },
});

Notificaciones de progreso

Una herramienta puede informar su progreso llamando reportProgress en el objeto de contexto:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { reportProgress }) => {
    reportProgress({
      progress: 0,
      total: 100,
    });

    // ...

    reportProgress({
      progress: 100,
      total: 100,
    });

    return "完了";
  },
});

recurso

Un recurso representa cualquier tipo de datos que un servidor MCP desea poner a disposición de sus clientes. Esto incluye:

  • Contenido del archivo

  • Capturas de pantalla e imágenes

  • Archivos de registro

  • Y muchos más

Cada recurso se identifica mediante un URI único y puede contener texto o datos binarios.

server.addResource({
  uri: "file:///logs/app.log",
  name: "アプリケーションログ",
  mimeType: "text/plain",
  async load() {
    return {
      text: await readLogFile(),
    };
  },
});

[!NOTA]

load puede devolver múltiples recursos. Esto se puede utilizar, por ejemplo, para devolver una lista de los archivos de un directorio cuando se lee dicho directorio.

async load() {
  return [
    {
      text: "1つ目のファイルの内容",
    },
    {
      text: "2つ目のファイルの内容",
    },
  ];
}

También puedes devolver contenido binario con load :

async load() {
  return {
    blob: 'base64でエンコードされたデータ'
  };
}

Plantillas de recursos

También puedes definir plantillas de recursos:

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "アプリケーションログ",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "ログの名前",
      required: true,
    },
  ],
  async load({ name }) {
    return {
      text: `${name}のサンプルログ内容`,
    };
  },
});

Completado automático de argumentos de plantillas de recursos

Para habilitar el autocompletado de los argumentos de la plantilla de recursos, proporcionamos una función complete :

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "アプリケーションログ",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "ログの名前",
      required: true,
      complete: async (value) => {
        if (value === "サンプル") {
          return {
            values: ["サンプルログ"],
          };
        }

        return {
          values: [],
        };
      },
    },
  ],
  async load({ name }) {
    return {
      text: `${name}のサンプルログ内容`,
    };
  },
});

inmediato

Prompts permite que el servidor defina plantillas de prompts y flujos de trabajo reutilizables que los clientes pueden presentar fácilmente a sus usuarios y LLM. Esto proporciona una forma poderosa de estandarizar y compartir interacciones LLM comunes.

server.addPrompt({
  name: "git-commit",
  description: "Gitコミットメッセージを生成します",
  arguments: [
    {
      name: "changes",
      description: "Gitの差分または変更の説明",
      required: true,
    },
  ],
  load: async (args) => {
    return `これらの変更に対する簡潔かつ説明的なコミットメッセージを生成してください：\n\n${args.changes}`;
  },
});

Completado automático de argumentos de solicitud

El mensaje puede proporcionar autocompletado de argumentos:

server.addPrompt({
  name: "countryPoem",
  description: "国についての詩を書きます",
  load: async ({ name }) => {
    return `こんにちは、${name}さん！`;
  },
  arguments: [
    {
      name: "name",
      description: "国の名前",
      required: true,
      complete: async (value) => {
        if (value === "日") {
          return {
            values: ["日本"],
          };
        }

        return {
          values: [],
        };
      },
    },
  ],
});

Completado automático de argumentos de solicitud mediante enum

Si proporciona una matriz enum para los argumentos, el servidor completará automáticamente los argumentos.

server.addPrompt({
  name: "countryPoem",
  description: "国についての詩を書きます",
  load: async ({ name }) => {
    return `こんにちは、${name}さん！`;
  },
  arguments: [
    {
      name: "name",
      description: "国の名前",
      required: true,
      enum: ["日本", "フランス", "イタリア"],
    },
  ],
});

proceso de dar un título

FastMCP le permite authenticate clientes mediante una función personalizada:

import { AuthError } from "fastmcp";

const server = new FastMCP({
  name: "マイサーバー",
  version: "1.0.0",
  authenticate: ({request}) => {
    const apiKey = request.headers["x-api-key"];

    if (apiKey !== '123') {
      throw new Response(null, {
        status: 401,
        statusText: "Unauthorized",
      });
    }

    // ここで返すものは`context.session`オブジェクトでアクセスできます
    return {
      id: 1,
    }
  },
});

Ahora puedes acceder a los datos de la sesión autenticada en tus herramientas:

server.addTool({
  name: "sayHello",
  execute: async (args, { session }) => {
    return `こんにちは、${session.id}さん！`;
  },
});

sesión

session es una instancia de FastMCPSession y describe una sesión de cliente activa.

server.sessions;

Para permitir la comunicación uno a uno entre el cliente y el servidor, se asigna una nueva instancia de servidor para cada conexión de cliente.

Eventos de servidor tipificados

Puedes escuchar los eventos emitidos por el servidor utilizando el método on :

server.on("connect", (event) => {
  console.log("クライアント接続:", event.session);
});

server.on("disconnect", (event) => {
  console.log("クライアント切断:", event.session);
});

FastMCPSession

FastMCPSession representa una sesión de cliente y proporciona métodos para interactuar con el cliente.

Consulte el ejemplo de sesión para saber cómo obtener FastMCPSession .

requestSampling

requestSampling realiza una solicitud de muestreo y devuelve la respuesta.

await session.requestSampling({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "現在のディレクトリにはどのファイルがありますか？",
      },
    },
  ],
  systemPrompt: "あなたは役立つファイルシステムアシスタントです。",
  includeContext: "thisServer",
  maxTokens: 100,
});

clientCapabilities

clientCapabilities contiene las capacidades del cliente.

session.clientCapabilities;

loggingLevel

loggingLevel describe el nivel de registro establecido por el cliente.

session.loggingLevel;

roots

roots contiene las rutas establecidas por el cliente.

session.roots;

server

server contiene la instancia del servidor MCP asociado con la sesión.

session.server;

Eventos de sesión tipificados

Puedes escuchar los eventos emitidos por la sesión utilizando on :

session.on("rootsChanged", (event) => {
  console.log("ルート変更:", event.roots);
});

session.on("error", (event) => {
  console.error("エラー:", event.error);
});

Ejecución del servidor

Prueba con MCP-CLI

La forma más rápida de probar y depurar su servidor es usar fastmcp dev :

npx fastmcp dev server.js
npx fastmcp dev server.ts

Esto ejecutará un servidor para probar y depurar su servidor MCP en la terminal usando mcp-cli .

Inspeccionar con MCP Inspector

Otra opción es inspeccionar su servidor en la interfaz web utilizando el MCP Inspector :

npx fastmcp inspect server.ts

Preguntas frecuentes

¿Cómo utilizar con Claude Desktop?

Siga la guía https://modelcontextprotocol.io/quickstart/user y agregue la siguiente configuración:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "tsx",
        "/プロジェクトへのパス/src/index.ts"
      ],
      "env": {
        "環境変数名": "値"
      }
    }
  }
}

Estudio de caso

[!NOTA]

Si ha desarrollado un servidor utilizando FastMCP, envíe una solicitud de colaboración y preséntela como caso de estudio.

Expresiones de gratitud

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Looking for Admin?

Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yamato-snow/2025_McpLab_FastMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server