picomcp docs

English · Français · Deutsch · Italiano · Español · Русский · 简体中文 · 日本語

picomcp is a zero-dependency TypeScript framework for Model Context Protocol servers. Give any LLM real tools in one file: typed with your schema library, served over stdio or HTTP, running on Node, Bun, Deno and the edge.

import { pico } from "picomcp";
import { z } from "zod";

pico({ name: "weather" })
  .tool("forecast", {
    description: "Get the forecast for a city.",
    input: z.object({ city: z.string() }),
    run: ({ city }) => getForecast(city),
  })
  .serve();

That is a complete server. Read the docs →

Why picomcp

Install

npm i picomcp zod        # or: bun add · pnpm add · deno add npm:picomcp

Or scaffold a project with a server, an entry point and a test:

npx picomcp init my-server

A tour in five snippets

Tools are functions the model calls. Return a string, an object, media, or throw:

server.tool("search_issues", {
  description: "Search open issues. Use it before filing a new one.",
  input: z.object({ query: z.string(), limit: z.number().max(50).default(10) }),
  annotations: { readOnlyHint: true },
  run: async ({ query, limit }, { signal }) => searchIssues(query, limit, { signal }),
});

Structured output is validated and sent as structuredContent:

server.tool("get_price", {
  input: z.object({ sku: z.string() }),
  output: z.object({ cents: z.number().int(), currency: z.literal("EUR") }),
  run: async ({ sku }) => ({ cents: await priceOf(sku), currency: "EUR" }),
});

Resources use URI templates whose variables are typed from the string:

server.resource("github://{owner}/{repo}/readme", {
  mimeType: "text/markdown",
  read: ({ owner, repo }) => fetchReadme(owner, repo), // owner: string, repo: string
});

Prompts become slash commands in clients:

server.prompt("review", {
  args: z.object({ diff: z.string().describe("The diff to review") }),
  run: ({ diff }) => `Review this diff for bugs:\n\n${diff}`,
});

Transports are one line each:

await server.serve();                        // stdio, for local clients
await server.serve({ http: 3000 });          // Streamable HTTP on Node, Bun or Deno
export default { fetch: server.fetch };      // Cloudflare Workers, Deno Deploy, Bun…

Connect a client

claude mcp add weather -- node /absolute/path/server.ts                     # Claude Code, stdio
claude mcp add --transport http weather https://example.com/mcp             # Claude Code, HTTP
npx @modelcontextprotocol/inspector node /absolute/path/server.ts           # MCP Inspector

Claude Desktop, Cursor and VS Code configs are in Connect a client.

Test it

import { expect, it } from "vitest";
import { server } from "./server.ts";

it("forecasts", async () => {
  const result = await server.call("forecast", { city: "Lyon" });
  expect(result.isError).toBeUndefined();
});

Docs for humans and agents

The documentation has typo-tolerant search on ⌘ K, and every page is also published for AI agents:

• llms.txt: an index of every page
• llms-full.txt: the whole documentation in one file
• docs/<page>.md: any page as Markdown
• picomcp-docs: the docs as an MCP server, built with picomcp. claude mcp add picomcp-docs -- npx -y picomcp-docs

Scope

picomcp is the server half of MCP, built for the stateless request/response model that most servers need. It covers lifecycle, tools (with structured output and annotations), resources and templates, prompts, cancellation and both transports.

It does not yet support features that need the server to message the client on its own: sampling, elicitation, roots, logging and progress notifications, subscriptions. If you need those today, use the official @modelcontextprotocol/sdk. The full list is in Protocol coverage.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first, then:

git clone https://github.com/picomcp/picomcp && cd picomcp
npm install
npm run check    # typecheck, tests, build, size budget, package lint

Working with a coding agent? It will find its instructions in AGENTS.md.

License

MIT