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)

# Install globally or locally
npm install -g expressjs-mcp
# or with pnpm
pnpm add -g expressjs-mcp

# Use with npx (no installation required)
npx expressjs-mcp init

Option 2: Clone and build locally

git clone https://github.com/bowen31337/expressjs_mcp.git
cd expressjs_mcp
pnpm install && pnpm build

Quick Start

Option 1: CLI Commands (Recommended)

# Initialize in your project (works with npm package or locally built)
npx expressjs-mcp init
# or if installed locally: node bin/express-mcp.cjs init

# Start your server
node server.js

# Test connection
npx expressjs-mcp test --url http://localhost:3000/mcp
# or if installed locally: node bin/express-mcp.cjs test --url http://localhost:3000/mcp

Option 2: Manual Setup

npm install expressjs-mcp
# or
pnpm add expressjs-mcp

Native MCP Server (New!)

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

# Connect to your Express app
npx expressjs-mcp --url http://localhost:3000/mcp

# With debug logging
npx expressjs-mcp --debug

import express from 'express';
import { ExpressMCP } from 'expressjs-mcp';

const app = express();
app.use(express.json());

app.get('/hello', (_req, res) => res.json({ message: 'world' }));

const mcp = new ExpressMCP(app, { mountPath: '/mcp' });
await mcp.init();
mcp.mount('/mcp');

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

Open Cursor Settings:
- Press Cmd/Ctrl + , to open settings
- Search for "MCP" or navigate to Extensions > MCP

Add MCP Server Configuration:

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

Alternative: Use Native MCP Server:

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

For Claude Desktop

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

Add MCP Server:

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

Restart Claude Desktop after making changes

For Claude Web

Access MCP Settings:
- Go to claude.ai
- Click on your profile/settings
- Look for "MCP Configuration" or "Model Context Protocol"

Add Server Configuration:

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

For VS Code with MCP Extension

Install MCP Extension:
- Search for "MCP" in VS Code extensions
- Install the official MCP extension

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:

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

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

Start your Express server:
```
node server.js
```

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": {}}'

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:

Path Issues: Use absolute paths in your configuration
Permission Issues: Ensure the server file is executable
Port Conflicts: Make sure your Express server is running on the expected port
Environment Variables: Set NODE_ENV=production for better performance

Debug Mode:

# Run with debug logging
NODE_ENV=development node server.js

# Or use the native MCP server with debug
npx expressjs-mcp --url http://localhost:3000/mcp --debug

Check MCP Server Status:

# Test if MCP endpoints are working
curl http://localhost:3000/mcp/tools | jq .

# Check server health
curl http://localhost:3000/health

Streaming Support

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

🌊 1. HTTP Chunked Streaming

app.get('/api/chunked', (req, res) => {
  res.setHeader('Transfer-Encoding', 'chunked');
  res.write('Processing...\n');
  // Stream data in chunks
});

📡 2. Server-Sent Events (SSE)

app.get('/api/sse', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  
  let count = 0;
  const interval = setInterval(() => {
    res.write(`data: ${JSON.stringify({ count: ++count })}\n\n`);
    if (count >= 10) {
      clearInterval(interval);
      res.end();
    }
  }, 1000);
});

📄 3. NDJSON/JSON Lines

app.get('/api/ndjson', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  
  const data = [{ id: 1 }, { id: 2 }];
  data.forEach(item => {
    res.write(JSON.stringify(item) + '\n');
  });
  res.end();
});

Testing All Streaming Types

# HTTP Streaming via MCP
curl -X POST http://localhost:3000/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{"toolName": "GET /api/stream", "args": {}, "streaming": true}'

# stdio Streaming via MCP Bridge (npm package)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"GET /api/ndjson","arguments":{"_streaming":true}}}' | \
  npx expressjs-mcp bridge
  
# Test with native MCP server:
npx expressjs-mcp --url http://localhost:3000/mcp --debug

# Direct endpoint testing
curl http://localhost:3000/api/sse        # SSE
curl http://localhost:3000/api/ndjson     # NDJSON
curl http://localhost:3000/api/chunked    # Chunked

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

pnpm install
pnpm test      # Run tests
pnpm build     # Build for production
pnpm lint      # Check code quality

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

expressjs-mcp

express_mcp

Features

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!)

MCP Client Configuration

For Cursor IDE

For Claude Desktop

For Claude Web

For VS Code with MCP Extension

For Other MCP Clients

Configuration Options

Testing Your Configuration

Troubleshooting

Streaming Support

🌊 1. HTTP Chunked Streaming

📡 2. Server-Sent Events (SSE)

📄 3. NDJSON/JSON Lines

Testing All Streaming Types

Documentation

Development

Configuration Options

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

expressjs-mcp

express_mcp

Features

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!)

MCP Client Configuration

For Cursor IDE

For Claude Desktop

For Claude Web

For VS Code with MCP Extension

For Other MCP Clients

Configuration Options

Testing Your Configuration

Troubleshooting

Streaming Support

🌊 1. HTTP Chunked Streaming

📡 2. Server-Sent Events (SSE)

📄 3. NDJSON/JSON Lines

Testing All Streaming Types

Documentation

Development

Configuration Options

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads