How to fix MCP server crashing on startup

1# 1. Find the command in your config
2# For example, if your config has:
3# "command": "node", "args": ["./dist/index.js"]
4
5# 2. Set environment variables
6export API_KEY="your-key-here"
7export DATABASE_URL="your-db-url"
8
9# 3. Run the exact command
10node ./dist/index.js
11
12# For npx servers:
13npx -y @modelcontextprotocol/server-github
14
15# For Python servers:
16uvx mcp-server-git --repository /path/to/repo
17
18# The error output will show exactly what went wrong

1# Error you might see:
2# "Error: Cannot find module '@modelcontextprotocol/sdk'"
3# "Error: Cannot find module 'zod'"
4# "MODULE_NOT_FOUND"
5
6# Fix for local servers:
7cd /path/to/your/mcp-server
8npm install
9npm run build  # if TypeScript
10
11# Fix for npx servers (clear cache):
12npm cache clean --force
13npx -y @modelcontextprotocol/server-github  # re-downloads
14
15# Fix for Python servers:
16uvx --reinstall mcp-server-git

1# Check your Node.js version
2node --version
3# Must be v18.0.0 or later
4
5# Common version-related errors:
6# "SyntaxError: Unexpected token 'export'"
7# "ERR_UNKNOWN_FILE_EXTENSION: .mjs"
8# "SyntaxError: Cannot use import statement outside a module"
9
10# Upgrade Node.js:
11# macOS with Homebrew:
12brew install node@20
13
14# Using nvm:
15nvm install 20
16nvm use 20
17
18# Verify after upgrade:
19node --version

1# Error messages indicating missing env vars:
2# "FATAL: API_KEY environment variable is required"
3# "Error: Missing required configuration: GITHUB_PERSONAL_ACCESS_TOKEN"
4# "Environment variable DATABASE_URL is not set"
5
6# Fix: add the variable to your host config
7{
8  "mcpServers": {
9    "my-server": {
10      "command": "node",
11      "args": ["./dist/index.js"],
12      "env": {
13        "API_KEY": "your-key-here"
14      }
15    }
16  }
17}

1// Wrap server initialization in try-catch
2try {
3  // Validate environment
4  const apiKey = process.env.API_KEY;
5  if (!apiKey) throw new Error("API_KEY is required");
6
7  // Initialize external connections
8  const db = await connectToDatabase(process.env.DATABASE_URL);
9  console.error("Database connected");
10
11  // Create and start MCP server
12  const server = new McpServer({ name: "my-server", version: "1.0.0" });
13  registerTools(server, db);
14
15  const transport = new StdioServerTransport();
16  await server.connect(transport);
17  console.error("MCP server ready");
18} catch (error) {
19  console.error("FATAL: Server failed to start:");
20  console.error(error instanceof Error ? error.stack : String(error));
21  process.exit(1);
22}