Installing Your First MCP Server

Module 2: Installing Your First MCP Server

Theory is easy. Let’s actually install something.

We’ll use the filesystem MCP server — the one that lets Claude read and write files on your machine. It’s a good first server because it’s official (maintained by Anthropic), simple to configure, and immediately useful without needing API keys or external accounts.

What You Need

• Claude Code installed and working
• Node.js (version 18 or later)
• A terminal

That’s it. No special accounts. No API credentials. Just the filesystem server talking to your local machine.

Step 1: Find the Package

The filesystem server lives at @modelcontextprotocol/server-filesystem on npm. You don’t install it the way you’d install a tool you run directly — MCP servers are launched on demand by Claude Code, so you reference the package and Claude Code handles running it.

You can verify the package exists and see its current version:

npm info @modelcontextprotocol/server-filesystem

If that returns package information, you’re ready to configure it.

Step 2: Open Your Claude Code Settings

Claude Code stores its configuration in ~/.claude/settings.json. This file controls which MCP servers are available. Open it in any text editor.

If the file doesn’t exist yet, create it. If it exists, look for an mcpServers key. If that key doesn’t exist, you’ll add it.

Step 3: Add the Server Configuration

Here’s what the filesystem server configuration looks like:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Dev"
      ]
    }
  }
}

Replace the path arguments with directories you actually want Claude to access. The server will be limited to those directories — it can’t read files outside them. Start with one or two directories you’re comfortable with.

The command is npx because we’re using npx to run the package without a global install. The -y flag auto-accepts the package download. The paths after the package name are the allowed directories.

Step 4: Restart Claude Code

MCP servers are loaded at session startup. If you edited the settings file while Claude Code was running, your changes won’t take effect until you restart.

Close Claude Code completely and open it again. Not just a new session — close the application.

Step 5: Verify It Works

Start a new session. Ask Claude:

“What MCP tools do you have available?”

Claude should list the filesystem tools: read_file, read_multiple_files, write_file, edit_file, create_directory, list_directory, directory_tree, move_file, search_files, get_file_info. If you see those, the server is running.

Then test it:

“List the files in my Documents folder.”

If Claude returns a file listing rather than saying it can’t access your filesystem, you’re done. The server is working.

When Something Goes Wrong

Claude doesn’t see the tools. First check you actually restarted (not just a new chat). Then check your settings.json syntax — JSON is picky about commas and quotes. Copy the JSON into a validator if you’re not sure.

npx download errors. If your network blocks npm or you’re offline, npx can’t download the package on first run. The fix is to install it globally first: npm install -g @modelcontextprotocol/server-filesystem, then use node as the command pointing to the installed binary instead of npx.

Permission errors. If Claude tries to read a directory and gets a permission error, check that the directory paths in your config are ones your user account can read. Also check you haven’t specified a path that doesn’t exist.

Claude says it has the tools but they fail. Usually a path issue in the config. Double-check the directory paths match what’s actually on your machine, including capitalisation.

What the Configuration Options Mean

Every MCP server entry in settings.json has the same shape:

"server-name": {
  "command": "the executable to run",
  "args": ["array", "of", "arguments"],
  "env": {
    "ENV_VAR": "value"
  }
}

command is what gets executed. Usually npx for npm packages, node for scripts, python for Python servers, or a direct path to a binary.

args is the array of arguments passed to that command. For npx, this includes the package name. For node, it’s the path to the script. Additional arguments configure the server itself.

env is optional. You use it to pass environment variables — API keys, configuration values, anything the server needs that shouldn’t go in the args.

Servers That Need API Keys

The filesystem server needs no credentials — it just talks to your local machine. Most servers that connect to external services need credentials. The pattern looks like this, for something like a GitHub server:

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
  }
}

The token goes in env, not in the args array. Never put credentials in the args — they can show up in process listings. The env approach keeps them out of that exposure surface.

---

You’ve got a working MCP server. Module 3 looks at which servers are worth installing and how to evaluate ones you find in the wild.