Write a handler once, get

• MCP tools
• REST endpoints
• n8n nodes
• Swagger/OpenAPI automatically.

1. What Is It?

easy-mcp-server watches the api/ folder and turns every file into:

| You provide | You get automatically | |-------------|-----------------------| | api/foo/get.ts style handlers | MCP tools (api__foo__get) || REST routes GET /foo | | Request/Response classes | MCP tools and OpenAPI schema + Swagger UI | | npm run n8n:generate | n8n nodes that mirror your APIs |

Everything hot-reloads and ships with zero config.

2. Quick Start

npx easy-mcp-server init my-project
cd my-project
./start.sh

| Service | URL | |---------|-----| | MCP Server | http://localhost:8888 | | REST API | http://localhost:8887 | | Swagger UI | http://localhost:8887/docs | | OpenAPI Spec | http://localhost:8887/openapi.json |

Stop the stack with ./stop.sh.

3. Define an Endpoint

File Name = Route (Examples)

| File | Method | Route | |------|--------|-------| | api/users/get.ts | GET | /users | | api/users/post.ts | POST | /users | | api/users/[id]/get.ts | GET | /users/:id |

Minimal Handler Template

Request block

// @description('Incoming payload')
class Request {
  // @description('User name')
  name: string;
  // @description('User email')
  email: string;
}

Response block

// @description('Response payload')
class Response {
  success: boolean;
  data: { id: string; name: string; email: string };
}

Handler block

// @summary('Create a user')
// @tags('users')
function handler(req: any, res: any) {
  const { name, email } = req.body;
  if (!name || !email) {
    res.status(400).json({ success: false, error: 'Name and email required' });
    return;
  }

  res.status(201).json({
    success: true,
    data: { id: '123', name, email }
  });
}

Export block

module.exports = handler;
export {};

Annotations (@description, @summary, @tags) feed OpenAPI docs and MCP tool metadata automatically.

4. System Architecture

See System Architecture documentation for detailed diagrams and flow explanations.

5. MCP Bridge (Optional)

Combine Other MCP Servers via mcp-bridge.json

{
  "mcpServers": {
    "chrome": {
      "command": "npx",
      "args": ["-y", "chrome-mcp-server"]
    }
  }
}

Hot reload keeps bridge tools and your API tools available on port 8888. Disable any bridge by adding "disabled": true.

6. Operations

| Command | Purpose | |---------|---------| | ./start.sh | Launch REST + MCP servers | | ./stop.sh | Stop them | | npm run n8n:generate | Refresh n8n nodes | | npm test | Run tests (where configured) |

| Env var | Default | Notes | |---------|---------|-------| | EASY_MCP_SERVER_PORT | 8887 | REST port | | EASY_MCP_SERVER_MCP_PORT | 8888 | MCP port | | EASY_MCP_SERVER_LOG_LEVEL | info | debug, info, warn, error | | EASY_MCP_SERVER_API_PATH | ./api | Folder to watch | | EASY_MCP_SERVER_HOST | 0.0.0.0 | Host binding |

7. Resources

• Architecture: docs/ARCHITECTURE.md
• Guide: docs/DEVELOPMENT.md
• Example project: example-project/
• Swagger: http://localhost:8887/docs
• OpenAPI: http://localhost:8887/openapi.json
• MCP endpoint: http://localhost:8888

8. Support & Contributions

| Topic | Details | |-------|---------| | Questions / Enterprise Support | [email protected] | | Licensed | MIT | | Maintainer | Boqiang Liang ([email protected]) |