expressjs-mcp

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