zcaceres/easy-mcp

> EasyMCP is usable but in beta. Please report any issues you encounter.
EasyMCP is the simplest way to create Model Context Protocol (MCP) servers in TypeScript.
It hides the plumbing, formatting, and other boilerplate definitions behind simple declarations.
Easy MCP allows you to define the bare minimum of what you need to get started. Or you can define more complex resources, templates, tools, and prompts.
## Features
Simple Express-like API: EasyMCP provides a high-level, intuitive API. Define Tools, Prompts, Resources, Resource Templates, and Roots with calls similar to defining endpoints in ExpressJS. Every possible parameter that could be optional is optional and hidden unless you need it.
Experimental Decorators API: Automagically infers tool, prompt, and resource arguments. No input schema definition required!
Context Object: Access MCP capabilities like logging and progress reporting through a context object in your tools.
Great Type Safety: Better DX and fewer runtime errors.
## Beta Limitations
No support for MCP sampling, yet
No support for SSE, yet
No resource update notifications, yet
Prompts technically accept inputs, but the Typescript SDK suggests they can't. So this functionality feels unfinished.
## Installation
To install EasyMCP, run the following command in your project directory:
bash
bun install
## Quick Start with (Experimental) Decorators API
Also see examples/express-decorators.ts or run bun start:decorators
EasyMCP's decorator API is dead simple and infers types and input configuration automatically.
But it's experimental and may change or have not-yet-discovered problems.
typescript
import EasyMCP from "./lib/EasyMCP";
import { Tool, Resource, Prompt } from "./lib/experimental/decorators";
class MyMCP extends EasyMCP {
@Resource("greeting/{name}")
getGreeting(name: string) {
return Hello, ${name}!;
@Prompt()
greetingPrompt(name: string) {
return Generate a greeting for ${name}.;
@Tool()
greet(name: string, optionalContextFromServer: Context) {
optionalContextFromServer.info(Greeting ${name});
return Hello, ${name}!;
const mcp = new MyMCP({ version: "1.0.0" });
## Complex Example with Decorators API
See examples/express-express.ts or run bun start:express
typescript
import EasyMCP from "./lib/EasyMCP";
import { Prompt } from "./lib/decorators/Prompt";
import { Resource } from "./lib/decorators/Resource";
import { Root } from "./lib/decorators/Root";
import { Tool } from "./lib/decorators/Tool";
@Root("/my-sample-dir/photos")
@Root("/my-root-dir", { name: "My laptop's root directory" }) // Optionally you can name the root
class ZachsMCP extends EasyMCP {
You can declare a Tool with zero configuration. Relevant types and plumbing will be inferred and handled.
By default, the name of the Tool will be the name of the method.
@Tool()
simpleFunc(nickname: string, height: number) {
return ${nickname} of ${height} height;
You can enhance a tool with optional data like a description.
Due to limitations in Typescript, if you want the Tool to serialize certain inputs as optional to the Client, you need to provide an optionals list.
@Tool({
description: "An optional description",
optionals: ["active", "items", "age"],