README.md
Expose your Hono API endpoints as MCP tools.
MCP Server for Hono
Expose your Hono API endpoints as MCP tools.
Usage
import { Hono } from "hono";
import { z } from "zod";
import { mcp, registerTool } from "hono-mcp-server";
const app = new Hono()
.get("/users", registerTool("List all users"), (c) => c.json([{ id: 1, name: "Alice" }]))
.get("/users/:id", registerTool("Get user by ID"), (c) => c.json({ id: c.req.param("id") }))
.post(
"/users",
registerTool({
description: "Create a new user",
inputSchema: {
name: z.string().describe("User's full name"),
email: z.string().email().describe("User's email address"),
},
}),
async (c) => {
const { name } = c.req.valid("json"); // typed!
return c.json({ id: 1, name });
},
);
export default mcp(app, {
name: "Users API",
version: "1.0.0",
});
This adds an /mcp endpoint that exposes your routes as MCP tools.
Input & Output Schemas
Use registerTool() with inputSchema for validated, typed input. Access validated data with c.req.valid('json'):
import { z } from "zod";
import { registerTool } from "hono-mcp-server";
app.post(
"/search",
registerTool({
description: "Search for items",
inputSchema: {
query: z.string().describe("Search query"),
limit: z.number().optional().describe("Max results"),
},
outputSchema: {
results: z.array(z.object({ id: z.string(), title: z.string() })),
},
}),
async (c) => {
const { query, limit } = c.req.valid("json"); // typed!
return c.json({ results: [] });
},
);
When outputSchema is defined, the tool returns structured content that MCP clients can parse.
Options
mcp(app, {
name: "API Name", // required
version: "1.0.0", // required
description: "...", // optional
instructions: "...", // optional
mcpPath: "/mcp", // optional, default: "/mcp"
codemode: false, // optional, see below
});
Codemode
Instead of exposing individual routes as tools, codemode exposes search and execute tools for dynamic API interaction. Requires Cloudflare Worker Loader.
export default mcp(app, {
name: "API",
version: "1.0.0",
codemode: true,
});
// wrangler.jsonc
{
"worker_loaders": [{ "binding": "LOADER" }],
}
Tools (3)
registerToolExposes a specific Hono API route as an MCP tool with optional input and output schema validation.searchDynamic API interaction tool available when codemode is enabled.executeDynamic API execution tool available when codemode is enabled.Configuration
claude_desktop_config.json
{
"mcpServers": {
"hono": {
"command": "npx",
"args": ["-y", "hono-mcp-server"]
}
}
}Try it
→List all users from the API.
→Create a new user with the name John Doe and email john@example.com.
→Search for items matching the query 'typescript' with a limit of 5.
→Get the details for user ID 123.