Installing Your First MCP Server

This guide will walk you through installing your first MCP server step by step. We'll use the Filesystem server as an example, as it's one of the most useful and straightforward servers to get started with.

Understanding MCP Server Types

MCP servers come in different forms, and the installation method depends on the type:

Step 1: Choose Your Server

For this guide, we'll install the official Filesystem server. This server allows your AI to read and write files on your computer with your permission.

Browse our server directory to find other servers that match your needs. Each server page includes specific installation instructions.

Step 2: Verify Prerequisites

Open your terminal and verify that you have the required tools installed:

If you don't have Node.js installed, download it from nodejs.org.

Step 3: Test the Server (Optional but Recommended)

Before adding the server to your configuration, it's a good idea to test that it runs correctly:

Replace /path/to/allowed/directory with an actual directory path on your system. For example:

• macOS/Linux: /Users/yourname/Documents
• Windows: C:\\Users\\yourname\\Documents

If the server starts successfully, you'll see initialization messages. Press Ctrl+C to stop the test.

Step 4: Locate Your Configuration File

MCP clients use a configuration file to know which servers to connect to. The location depends on your operating system and client:

Step 5: Add Server to Configuration

Open the configuration file in a text editor. If the file doesn't exist, create it. Add the following configuration:

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

Step 6: Restart Your MCP Client

For the changes to take effect, you need to completely quit and restart your MCP client:

1. Quit Claude Desktop completely (not just close the window)
2. Wait a few seconds
3. Launch Claude Desktop again
4. The server should now be connected and ready to use

Step 7: Verify the Installation

To verify that the server is working correctly, try asking your AI to perform a file operation:

If the server is working, your AI should be able to perform these operations. If you see errors, check the troubleshooting section below.

Adding Multiple Servers

You can add multiple MCP servers to your configuration. Here's an example with several servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents"
      ]
    },
    "git": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-git",
        "--repository",
        "/Users/yourname/projects/myrepo"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    }
  }
}

Troubleshooting Common Issues

Server Not Appearing in Client

If your server doesn't show up after restarting:

• Check that the configuration file is in the correct location
• Verify the JSON syntax is valid (use a JSON validator)
• Make sure you completely quit and restarted the client
• Check the client's logs for error messages

Permission Denied Errors

If you see permission errors:

• Verify the directory path exists and is accessible
• Check that your user account has read/write permissions
• On macOS, you may need to grant Full Disk Access to Claude Desktop in System Preferences
• Try using a directory in your home folder instead of system directories

Server Fails to Start

If the server won't start:

• Verify Node.js/Python is installed and in your PATH
• Try running the server command manually in terminal to see detailed errors
• Check that all required dependencies are installed
• Look for typos in the command or arguments

Finding Logs

Claude Desktop logs can help diagnose issues:

• macOS: ~/Library/Logs/Claude/
• Windows: %APPDATA%\\Claude\\logs\\
• Linux: ~/.config/Claude/logs/

Server-Specific Installation Notes

Python-Based Servers

For Python servers, use uvx instead of npx:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/path/to/database.db"
      ]
    }
  }
}

Servers Requiring API Keys

Some servers need API keys or credentials. Add them as environment variables:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Next Steps

Congratulations! You've successfully installed your first MCP server. Here's what to do next: