express_mcp

Expose your Express endpoints as MCP tools (mount to your app or run a standalone HTTP gateway), preserving schemas and auth behavior.

• Inspiration: FastAPI-MCP — https://github.com/tadata-org/fastapi_mcp

Features

• Zero Configuration: Works out-of-the-box with existing Express apps

• Schema Preservation: Supports OpenAPI v3 and zod annotations

• Auth Integration: Reuses existing Express middleware (no bypass)

• Flexible Deployment: Mount to same app or run standalone

• In-Process Efficiency: Direct middleware execution (no HTTP overhead)

• 🚀 Streaming Support: Handle Server-Sent Events, file downloads, and real-time data

• 📦 NPX/Bunx Commands: Easy CLI access with npx expressjs-mcp and bunx expressjs-mcp

Installation

Option 1: Install from npm (Recommended)

Option 2: Clone and build locally

Quick Start

Option 1: CLI Commands (Recommended)

Option 2: Manual Setup

Native MCP Server (New!)

Express-MCP now includes a native MCP server using the official @modelcontextprotocol/sdk:

MCP Client Configuration

Once your Express server is running with MCP endpoints, you need to configure your MCP client to connect to it. Here are instructions for popular MCP clients:

For Cursor IDE

1. Open Cursor Settings:

   • Press Cmd/Ctrl + , to open settings

   • Search for "MCP" or navigate to Extensions > MCP

2. Add MCP Server Configuration:

   { "mcpServers": { "expressjs-mcp": { "command": "node", "args": ["/path/to/your/project/server.js"], "env": { "NODE_ENV": "production" } } } }

3. Alternative: Use Native MCP Server:

   { "mcpServers": { "expressjs-mcp": { "command": "npx", "args": ["expressjs-mcp", "--url", "http://localhost:3000/mcp"] } } }

For Claude Desktop

1. Edit Configuration File:

   • Open claude_desktop_config.json in your Claude Desktop settings

   • Location varies by OS:

     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

     • Windows: %APPDATA%\Claude\claude_desktop_config.json

     • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add MCP Server:

   { "mcpServers": { "expressjs-mcp": { "command": "node", "args": ["/absolute/path/to/your/project/server.js"], "env": { "NODE_ENV": "production" } } } }

3. Restart Claude Desktop after making changes

For Claude Web

1. Access MCP Settings:

   • Go to claude.ai

   • Click on your profile/settings

   • Look for "MCP Configuration" or "Model Context Protocol"

2. Add Server Configuration:

   { "mcpServers": { "expressjs-mcp": { "command": "node", "args": ["/path/to/your/project/server.js"] } } }

For VS Code with MCP Extension

1. Install MCP Extension:

   • Search for "MCP" in VS Code extensions

   • Install the official MCP extension

2. Configure in settings.json:

   { "mcp.servers": { "expressjs-mcp": { "command": "node", "args": ["/path/to/your/project/server.js"] } } }

For Other MCP Clients

Most MCP clients follow a similar configuration pattern:

Configuration Options

• command: The command to run (usually node for JavaScript/TypeScript)

• args: Array of arguments (path to your server file)

• env: Environment variables (optional)

• cwd: Working directory (optional)

Testing Your Configuration

1. Start your Express server:

   node server.js

2. Test MCP endpoints:

   # Check available tools curl http://localhost:3000/mcp/tools # Test a tool invocation curl -X POST http://localhost:3000/mcp/invoke \ -H "Content-Type: application/json" \ -d '{"toolName": "GET_/hello", "args": {}}'

3. Verify in your MCP client:

   • The MCP client should show available tools

   • You should be able to invoke tools through the client interface

Troubleshooting

Common Issues:

1. Path Issues: Use absolute paths in your configuration

2. Permission Issues: Ensure the server file is executable

3. Port Conflicts: Make sure your Express server is running on the expected port

4. Environment Variables: Set NODE_ENV=production for better performance

Debug Mode:

Check MCP Server Status:

Streaming Support

Express MCP supports three types of streaming for real-time data:

🌊 1. HTTP Chunked Streaming

📡 2. Server-Sent Events (SSE)

📄 3. NDJSON/JSON Lines

Testing All Streaming Types

Documentation

• 🚀 Quick MCP Setup - Get started in 3 steps

• 📁 Examples & Tutorials - Complete example walkthroughs

• 🔧 Working MCP Configurations - IMPORTANT: Working configs before npm publish

• 🚀 Publishing & CI/CD - Automated npm publishing workflow

• MCP Client Setup - Detailed configuration guide

• Streaming Guide - Comprehensive streaming documentation

• Usage Guide - API reference and examples

• Architecture - Technical overview

• PRD - Product requirements

Development

Configuration Options

• OpenAPI: Provide your OpenAPI v3 spec for rich schemas

• Schema Annotations: Use zod for per-route type validation

• Route Filtering: Include/exclude specific endpoints

• Auth Preservation: Existing middleware runs unchanged

• Streaming: Automatic detection and handling of streaming responses

• Timeouts: Configurable request timeouts for long-running operations