How to Set Up Your MCP Development Environment

The one setup that breaks everything if you skip it

Before you write a single line of MCP server code, your development environment needs to be right. This sounds boring. It is boring. But getting it wrong means you'll spend hours chasing cryptic errors that have nothing to do with MCP itself.

We know this firsthand. Back when MCP first launched, a rogue outdated version of Node.js on a Mac caused a cascade of errors that looked like MCP bugs. They weren't. The protocol worked fine. The environment was the problem. Once Node was installed cleanly, every issue disappeared.

This guide walks you through every prerequisite, every install command, every configuration file. Follow it once, get it right, and your MCP development workflow stays clean from here on out.

Prerequisites you need before starting

You need three things on your machine before touching the MCP SDK. If you're missing any of them, the install steps below won't work.

Open your terminal and run both checks right now:

node --version
npm --version

If you see version numbers come back, you're in good shape. If you get "command not found" or a version below 16, you need to install or update Node.js from nodejs.org. The installer covers Mac, Windows, and Linux. Download the LTS version, run the installer, and verify again.

Why version 16 is the floor, but version 20 is the target. Node 16 introduced native fetch support and several async features that MCP servers depend on. Older versions will throw errors when you install community MCP servers or follow the official quick-start tutorial. Version 20 adds performance improvements and better compatibility with the TypeScript SDK. If you're installing fresh, go straight to 20 or higher.

> Having trouble installing Node? Paste any error messages directly into Claude, ChatGPT, or whichever AI model you have access to. AI models are remarkably good at diagnosing Node.js and npm installation problems. Describe your operating system, include the full error output, and you'll typically get a working fix in one response.

Create your project and install the MCP SDK

With Node and npm confirmed, you can set up a project folder and install everything the MCP TypeScript SDK needs. Here is the full sequence.

Step 1: Create your project folder and initialize it.

mkdir my-mcp-server && cd my-mcp-server
npm init -y

The npm init -y command generates a package.json file with default values. You'll modify it shortly.

Step 2: Install your core dependencies.

Three packages go into every MCP server project:

• @modelcontextprotocol/sdk: the official MCP TypeScript SDK that handles the protocol layer
• zod: a validation library the SDK uses to define input schemas for your tools
• Both are runtime dependencies your server needs when it runs

npm install @modelcontextprotocol/sdk zod

Step 3: Install your dev dependencies.

TypeScript itself and the Node.js type definitions are only needed during development, not at runtime.

npm install -D typescript @types/node

Step 4: Create the file structure.

mkdir src
touch src/index.ts

Your src/index.ts is where your server code lives. TypeScript compiles it into JavaScript that Node.js can actually execute. That compile step is what the next section configures.

Configure TypeScript and your build scripts

Two files control how your project compiles and runs: tsconfig.json and package.json. Both need specific settings for MCP servers to work correctly.

The TypeScript config. Create a tsconfig.json in your project root with these settings:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

What matters here: The outDir tells TypeScript to put compiled JavaScript files in a build/ folder. The rootDir points at your src/ folder where your TypeScript lives. The module and moduleResolution settings use Node16, which matches the ES module format MCP servers expect.

The package.json updates. Open your package.json and add or change these fields:

{
  "type": "module",
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  }
}

Setting "type": "module" tells Node.js to treat your files as ES modules. The build script does two things: it compiles TypeScript to JavaScript using tsc, then makes the output file executable with chmod. That executable permission matters because MCP clients like Claude Desktop need to run your server file directly.

Your complete project structure should look like this:

my-mcp-server/
├── node_modules/
├── src/
│   └── index.ts
├── package.json
├── package-lock.json
└── tsconfig.json

The compile-to-JavaScript workflow you'll repeat

Here is the pattern you'll follow every time you make changes to your MCP server. Write TypeScript in src/, compile it to JavaScript in build/, and point your MCP client at the compiled output.

The build command:

npm run build

This creates a build/ directory containing index.js, the compiled version of your TypeScript. When you configure Claude Desktop or any other MCP client to use your server, you point it at this compiled file, not the TypeScript source.

The full development cycle looks like this:

1. Edit src/index.ts with your server logic 2. Run npm run build to compile 3. Test by connecting your MCP client to build/index.js 4. See an error, fix the TypeScript, rebuild, test again

That's the entire loop. There's no hot-reload, no dev server, no watch mode required. You change the source, compile, and test. Each cycle takes seconds.

One common mistake: forgetting to rebuild after editing. If your changes aren't showing up in Claude Desktop, run npm run build again. The client reads the compiled JavaScript, not your source TypeScript. Stale builds are the number one cause of "my changes aren't working" confusion.

> Tip: If you want a file watcher that recompiles automatically on save, you can add a watch script to your package.json: "watch": "tsc --watch". Run it with npm run watch and it recompiles every time you save a file in src/. This is optional but saves you from manually running the build command during longer coding sessions.

Your environment is now ready. From here, every MCP server you build, whether it connects to a CRM, a project tracker, or a custom API, starts from this same foundation. The next step is writing your first server code inside src/index.ts.