mcp-stdio

Zero-dependency MCP server for stdio transport. Just tools, nothing else.

Why

The official MCP SDK has 17 dependencies (Express, Hono, OAuth, JWT...). Most MCP servers just need stdio + tools. This package is 222 lines, zero runtime dependencies.

Related MCP server: achmadya-dev/mcp-core

Install

npm install mcp-stdio

Usage

import { createMcpServer } from 'mcp-stdio';

createMcpServer({
  name: 'my-server',
  version: '1.0.0',
  tools: {
    greet: {
      description: 'Say hello',
      parameters: {
        type: 'object',
        properties: { name: { type: 'string' } },
        required: ['name'],
      },
      handler: async ({ name }) => `Hello ${name}!`,
    },

    add: {
      description: 'Add two numbers',
      parameters: {
        type: 'object',
        properties: {
          a: { type: 'number' },
          b: { type: 'number' },
        },
        required: ['a', 'b'],
      },
      handler: async ({ a, b }) => `${Number(a) + Number(b)}`,
    },
  },
});

Configure in Claude Code

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["my-server.js"]
    }
  }
}

API

createMcpServer(options)

Starts an MCP server reading JSON-RPC from stdin, writing to stdout.

Options:

ToolDefinition:

Handler return types:

• string — wrapped as [{ type: 'text', text: '...' }]

• ToolContent[] — returned as-is (supports text, image, resource)

Errors in handlers are caught and returned as { isError: true, content: [{ type: 'text', text: 'Error: ...' }] } — the server never crashes.

What it implements

• JSON-RPC 2.0 over stdio (newline-delimited)

• initialize with capability negotiation

• tools/list with JSON Schema input schemas

• tools/call with structured content responses

• ping

• Proper error codes (-32700, -32600, -32601, -32603)

• Notification handling (no response for messages without id)

• Logs to stderr (stdout is protocol-only)

What it doesn't implement

• HTTP/SSE/Streamable HTTP transport

• Resources, Prompts, Sampling

• OAuth, authentication

• Schema validation (trusts the caller — your handler validates)

These are intentional omissions. If you need them, use the official SDK.

License

MIT