FastMCP

FastMCP 是一个 TypeScript 框架，用于构建具有客户端会话管理的MCP服务器。

[！笔记]
对于 Python 实现，请参阅FastMCP Python 。

主要特点

FastMCP 提供以下功能：

简单的工具、资源和提示定义
认证功能
会话管理
图像内容支持
日志记录
错误处理
服务器发送事件 (SSE)
CORS（默认启用）
进度通知
类型化服务器事件
提示参数自动完成
采样请求
自动 SSE ping
路线管理
用于测试和调试的CLI

如何安装

npm install fastmcp

快速入门

[！笔记]
FastMCP 有许多现实世界的用例。请参阅案例研究。

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",
});

现在您有一个可以运行的 MCP 服务器！

您可以在终端中使用以下命令进行测试：

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) 是一种服务器通过 HTTPS 连接向客户端发送实时更新的机制。在 MCP 中，SSE 主要用于实现远程 MCP 通信，允许访问托管在远程机器上的 MCP 并通过网络传递更新。

您还可以运行支持 SSE 的服务器：

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

这将启动一个服务器，监听http://localhost:8080/sse上的 SSE 连接。

然后您可以使用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);

基本概念

工具

在 MCP工具中，服务器公开客户端和 LLM 可以调用来执行操作的可执行函数。

FastMCP 使用标准模式规范来定义工具参数。这使您可以使用实现规范的最喜欢的模式验证库，例如 Zod、ArkType 或 Valibot。

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);
  },
});

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);
  },
});

Valibot 的示例：

Valibot 需要对等依赖：@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);
  },
});

返回字符串

execute可以返回一个字符串：

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

这相当于：

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

返回列表

如果要返回消息列表，可以返回具有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つ目のメッセージ" },
      ],
    };
  },
});

返回图像

要创建图像内容对象，请使用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(...)
    //   ],
    // };
  },
});

imageContent函数接受以下选项：

url ：图片的 URL
path ：图像文件的路径
buffer ：图像数据作为缓冲区

必须指定url 、 path或buffer中的一个。

上面的例子等价于：

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

日志记录

工具可以使用上下文对象的log将消息记录到客户端：

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

    // ...

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

    return "完了";
  },
});

log对象有以下方法：

debug(message: string, data?: SerializableValue)
error(message: string, data?: SerializableValue)
info(message: string, data?: SerializableValue)
warn(message: string, data?: SerializableValue)

错误

应该向用户显示的错误应该作为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 "完了";
  },
});

进度通知

工具可以通过调用上下文对象上的reportProgress来报告其进度：

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 "完了";
  },
});

资源

资源代表 MCP 服务器想要向其客户端提供的任何类型的数据。其中包括：

文件内容
截图和图片
日志文件
以及更多

每个资源由唯一的 URI 标识，并且可以包含文本或二进制数据。

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

[！笔记]
load可以返回多个资源。例如，这可用于在读取目录时返回目录中的文件列表。
async load() { return [ { text: "1つ目のファイルの内容", }, { text: "2つ目のファイルの内容", }, ]; }

您还可以使用load返回二进制内容：

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

资源模板

您还可以定义资源模板：

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

资源模板参数的自动完成

为了实现资源模板参数的自动完成，我们提供了一个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}のサンプルログ内容`,
    };
  },
});

迅速的

Prompts允许服务器定义可重复使用的提示模板和工作流程，客户端可以轻松地将其呈现给其用户和 LLM。这为标准化和共享常见的 LLM 交互提供了一种强大的方法。

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

提示参数自动完成

提示可以提供参数的自动完成：

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: [],
        };
      },
    },
  ],
});

使用`enum`自动完成提示参数

如果您为参数提供enum数组，服务器将自动提供参数完成。

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

认证

FastMCP 允许您使用自定义函数对客户端authenticate ：

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,
    }
  },
});

您现在可以在工具中访问经过身份验证的会话数据：

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

会议

session对象是FastMCPSession的一个实例，描述一个活动的客户端会话。

server.sessions;

为了允许客户端和服务器之间的一对一通信，每个客户端连接都会分配一个新的服务器实例。

类型化服务器事件

您可以使用on方法监听服务器发出的事件：

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

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

`FastMCPSession`

FastMCPSession代表一个客户端会话并提供与客户端交互的方法。

请参阅Session示例以了解如何获取FastMCPSession实例。

`requestSampling`

requestSampling发出采样请求并返回响应。

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

`clientCapabilities`

clientCapabilities属性包含客户端功能。

session.clientCapabilities;

`loggingLevel`

loggingLevel属性描述客户端设置的日志记录级别。

session.loggingLevel;

`roots`

roots属性包含客户端设置的路线。

session.roots;

`server`

server属性包含与会话关联的 MCP 服务器的实例。

session.server;

类型化会话事件

您可以使用on方法监听会话发出的事件：

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

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

运行服务器

使用 MCP-CLI 进行测试

测试和调试服务器的最快方法是使用fastmcp dev ：

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

这将运行一个服务器，使用mcp-cli在终端中测试和调试您的 MCP 服务器。

使用 MCP Inspector 进行检查

另一种选择是使用官方MCP Inspector在 WebUI 中检查您的服务器：

npx fastmcp inspect server.ts

常问问题

如何与 Claude Desktop 一起使用？

按照指南https://modelcontextprotocol.io/quickstart/user并添加以下配置：

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

案例研究

[！笔记]
如果你已经使用 FastMCP 开发了服务器，请提交 PR并作为案例研究介绍！

apinetwork/piapi-mcp-server - 使用 Midjourney/Flux/Kling/LumaLabs/Udio/Chrip/Trellis 生成媒体
domdomegg/computer-use-mcp - 控制计算机
LiterallyBlah/Dradis-MCP - 使用 Dradis 进行项目和漏洞管理
Meeting-Baas/meeting-mcp - 创建会议机器人、搜索会议记录、管理记录数据
drumnation/unsplash-smart-mcp-server - 使 AI 代理能够无缝搜索、推荐和分发来自 Unsplash 的专业照片
ssmanji89/halopsa-workflows-mcp - 将 HaloPSA 工作流程与 AI 助手集成
aiamblichus/mcp-chat-adapter - 为 LLM 使用聊天完成功能提供简洁的界面

致谢

FastMCP 的灵感来自Jonathan Lowin的Python 实现。
部分代码库取自LiteMCP 。
部分代码库是从我们通过模型上下文协议对 SSE 进行的实验中采用的。

Integrations

FastMCP

主要特点

如何安装

快速入门

上交所

基本概念

工具

返回字符串

返回列表

返回图像

日志记录

错误

进度通知

资源

资源模板

资源模板参数的自动完成

迅速的

提示参数自动完成

使用enum自动完成提示参数

认证

会议

类型化服务器事件

FastMCPSession

requestSampling

clientCapabilities

loggingLevel

roots

server