by iolufemi
Express REST API and MCP Server Framework is a comprehensive development framework for building RESTful APIs and MCP servers with Express.js. It provides a complete template for creating production-ready APIs using Node.js, Express, Mongoose (MongoDB), and Sequelize (SQL databases).
# Add to your Claude Code skills
git clone https://github.com/iolufemi/Express-REST-API-and-MCP-Server-FrameworkExpress REST API and MCP Server Framework is a comprehensive development framework for building RESTful APIs with Express.js. It provides a complete template for creating production-ready APIs using Node.js, Express, Mongoose (MongoDB), and Sequelize (SQL databases). Every generated service exposes both REST endpoints and an MCP (Model Context Protocol) server so LLMs can interact with your API directly.
GitHub repository: iolufemi/Express-REST-API-and-MCP-Server-Framework
In computer programming, an application programming interface (API) is a set of clearly defined methods of communication between various software components. A good API makes it easier to develop a computer program by providing all the building blocks, which are then put together by the programmer. An API may be for a web-based system, operating system, database system, computer hardware or software library. Just as a graphical user interface makes it easier for people to use programs, application programming interfaces make it easier for developers to use certain technologies in building applications. - Wikipedia
Representational state transfer (REST) or RESTful web services is a way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations. -
No comments yet. Be the first to share your thoughts!
NOTE: The use of this project requires that you have a basic knowledge of using Express in building a REST API.
MCP (Model Context Protocol) is an open protocol that lets AI assistants (e.g. Claude, ChatGPT, Cursor) interact with your application through a standard interface. Instead of the LLM calling your REST API with raw HTTP, it uses MCP to discover and use tools (actions like create, update, delete) and resources (read-only data like list and get-by-id). - Wikipedia
This framework ships with a built-in MCP server. When you generate a service with npm run generate -- --name users, the same data is exposed as:
GET/POST/PUT/DELETE /users for apps and integrationscreate_users, update_users, list_users for LLMsusers://list, users://{id} for LLM contextYou get one codebase, dual access: traditional REST for clients and MCP for AI. See MCP Guide for setup (including Cursor) and details.
npm run generate -- --name <Name>)users.v1.ts map to /v1/users; latest stays at /usersnpm testClone the repository and install dependencies:
$ git clone https://github.com/iolufemi/Express-REST-API-and-MCP-Server-Framework.git ./yourProjectName
$ cd yourProjectName
$ npm install
| Command | Description |
|---------|-------------|
| npm run generate -- --name <Name> | Generate a MongoDB CRUD endpoint (route, controller, model, MCP registration, tests). Use -n for short. |
| npm run generate -- --name <Name> --sql | Generate a SQL CRUD endpoint (Sequelize model, SQL controller/routes/tests). |
| npm run generate -- --name <Name> --baseurl <URL> --endpoint <path> | Generate an API-as-DB endpoint (proxy to external API). Short: -n, -b, -e. |
| npm run dev | Start development server with hot reload |
| npm run build | Compile TypeScript to dist/ |
| npm start | Run production server |
| npm test | Run unit tests (Mocha, spec reporter) |
| npm run type-check | Run TypeScript type-check only |
| npm run release -- --release-type patch | Bump version, changelog, tag, and GitHub release (use minor or major for --release-type as needed) |
For release to create the GitHub release, set GITHUB_TOKEN, GIT_OAUTH_TOKEN, or CONVENTIONAL_GITHUB_RELEASER_TOKEN to a Personal Access Token: classic token needs repo scope; fine-grained token needs Releases: Read and write for this repository. Example: GITHUB_TOKEN=ghp_xxx npm run release -- --release-type patch. You can also use RELEASE_TYPE=minor npm run release (no extra args).
The generate script runs npx gulp --gulpfile gulpfile.cjs service so the correct gulpfile is always used (avoids "No gulpfile found" when running gulp directly).
Generate a complete CRUD service with both REST API and MCP server support using the generate script (runs the gulp service task with the correct config via npx):
$ npm run generate -- --name yourFirstEndpoint
Or using the short form:
$ npm run generate -- -n yourFirstEndpoint
This single command generates:
Why
npm run generate? The project usesgulpfile.cjs. Runninggulp servicedirectly can fail with "No gulpfile found". Thegeneratescript runsnpx gulp --gulpfile gulpfile.cjs service, so you don't need to install gulp globally or remember the gulpfile path.
With the generate command, you have the option of using either Mongo DB, an SQL compatible DB or using an API generated by this framework as a database model. To use an API as a database you can pass the baseurl and the endpoint option; for an SQL compatible db, pass the sql option. See examples below.
$ npm run generate -- --name yourEndpointWithAPIAsDB --baseurl http://localhost:8080 --endpoint users
See API as DB specification for the contract your API must implement and how to test for compliance.
Important for MCP: After generating an API-based model, you need to:
schemaObject in the generated model file to match the real data structuredescription and mcpDescription fields for each schema fieldThe generated template includes a schema definition section with examples - replace them with your actual API response fields. The schema endpoint (GET /{service}/schema) can optionally discover schema from the external API at GET {baseurl}/{endpoint}/schema; if that fails or is not available, it falls back to the _schema defined in the model file.
$ npm run generate -- --name yourEndpointWITHSQL --sql
Note: You can use
-ninstead of--name,-binstead of--baseurl,-einstead of--endpoint.
Try out your new endpoint.
Start the app
$ npm start
by default, the app will start on POST 8080
You can change the PORT by adding a PORT environment variable.
eg.
$ PORT=6000 npm start
now the app will start on PORT 6000
To start the app for development, run
$ npm run dev
This will automatically restart your app whenever a change is detected using tsx watch.
When you generate a service, you get access to:
[POST] http://localhost:8080/yourFirstEndpoint - Create resources (single or bulk)[GET] http://localhost:8080/yourFirstEndpoint - List/search resources (supports filters, pagination, sorting, projection, date range)[GET] http://localhost:8080/yourFirstEndpoint/:id - Get a specific resource[PUT] http://localhost:8080/yourFirstEndpoint - Update multiple resources (with query)[PATCH] http://localhost:8080/yourFirstEndpoint/:id - Update a single resource[DELETE] http://localhost:8080/yourFirstEndpoint?key=value - Delete multiple resources (with query)[DELETE] http://localhost:8080/yourFirstEndpoint/:id - Delete a single resource