MCP Reference Servers — User Guide

1. Quick Start

The Model Context Protocol (MCP) Reference Servers monorepo provides a collection of official, production-ready MCP server implementations. Each server exposes a focused set of tools that AI assistants (Claude, GPT, etc.) can call to interact with external systems — filesystems, Git repositories, web pages, knowledge graphs, time zones, and more.

Key features:

• Filesystem Server — secure, sandboxed file operations with 14 tools
• Git Server — full Git workflow (status, diff, commit, branch, log) via 12 tools
• Fetch Server — web page retrieval with robots.txt compliance and HTML-to-Markdown conversion
• Memory Server — persistent knowledge graph with entity/relation/observation CRUD
• Time Server — timezone queries and conversions using IANA timezone names
• Sequential Thinking Server — structured, revisable chain-of-thought reasoning
• Everything Server — reference implementation exercising all MCP protocol features

Prerequisites:

• Node.js 18+ (for TypeScript servers: filesystem, memory, sequential-thinking, everything)
• Python 3.10+ with uv (for Python servers: fetch, git, time)
• An MCP-compatible client (Claude Desktop, VS Code with Copilot, Cursor, etc.)

Fastest way to try a server (filesystem example):

npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Tip

Most MCP clients let you configure servers declaratively in a JSON file — you rarely need to run them manually. See the Configuration section below.

What to try next: configure your preferred server in your MCP client, then ask your AI assistant to use its tools (e.g., "read the file at /tmp/notes.txt" or "what time is it in Tokyo?").

2. Installation

System Requirements

Installing TypeScript Servers

The four TypeScript servers are published to npm as individual packages:

npx (no install)

npx -y @modelcontextprotocol/server-filesystem /path/to/directory

Global install

npm install -g @modelcontextprotocol/server-filesystem
mcp-server-filesystem /path/to/directory

From source

git clone https://github.com/modelcontextprotocol/servers.git
cd servers
npm install
npm run build
node src/filesystem/dist/index.js /path/to/directory

Installing Python Servers

The three Python servers are published to PyPI:

uvx (no install)

uvx mcp-server-fetch

pip install

pip install mcp-server-fetch
python -m mcp_server_fetch

Post-Install Verification

Verify a TypeScript server:

npx -y @modelcontextprotocol/server-filesystem --help

Usage: mcp-server-filesystem [allowed-directory] [additional-directories...]

Verify a Python server:

uvx mcp-server-fetch --help

Important

All servers communicate over stdio by default. They are designed to be launched by an MCP client, not run interactively in a terminal. Running them directly will appear to hang — this is normal; the server is waiting for MCP protocol messages on stdin.

3. Configuration

Each server is configured by adding an entry to your MCP client's configuration file. The exact file location depends on your client:

Filesystem Server Configuration

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

Pass one or more allowed directories as arguments. The server restricts all file operations to these directories and their subdirectories.

Warning

Choose allowed directories carefully. The AI assistant will have full read/write access to all files within them. Never allow your entire home directory or system paths.

Git Server Configuration

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/your/repo"]
    }
  }
}

The --repository argument is optional. When omitted, the server accepts a repo_path parameter with each tool call, and can also discover repositories via MCP roots.

Fetch Server Configuration

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Optional arguments:

Memory Server Configuration

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.jsonl"
      }
    }
  }
}

Tip

Set MEMORY_FILE_PATH to a location in your cloud-synced folder (e.g., Dropbox, iCloud Drive) to share memory across machines.

Time Server Configuration

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone", "America/New_York"]
    }
  }
}

The --local-timezone argument overrides automatic local timezone detection. Use IANA timezone names (e.g., Europe/London, Asia/Tokyo).

Sequential Thinking Server Configuration

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
      "env": {
        "DISABLE_THOUGHT_LOGGING": "false"
      }
    }
  }
}

Everything Server Configuration

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

The Everything Server supports three transport modes via its first argument:

For full configuration reference, see the Admin Guide.

4. Core Usage

Filesystem Operations

The Filesystem Server provides sandboxed file access. All paths must be within the allowed directories configured at startup.

Reading files:

Example — ask your AI assistant:

"Read the first 50 lines of /Users/me/project/config.yaml"

The assistant calls read_text_file with path: "/Users/me/project/config.yaml" and head: 50.

Writing and editing files:

Warning

write_file completely overwrites existing files without confirmation. Use edit_file for targeted modifications — it supports a dryRun mode that shows a git-style diff without making changes.

Directory operations:

Note

The deprecated read_file tool still works but is an alias for read_text_file. Use read_text_file in new configurations.

Git Operations

The Git Server wraps common Git commands as MCP tools. Each tool requires a repo_path parameter pointing to a valid Git repository.

Inspection tools (read-only):

Mutation tools:

Tip

The git_log tool supports timestamp filtering with flexible date formats: ISO 8601 (2024-01-15T14:30:25), relative (2 weeks ago, yesterday), or absolute (Jan 15 2024).

Web Fetching

The Fetch Server provides a single fetch tool and a fetch prompt for retrieving web content.

Tool: fetch

The server automatically converts HTML pages to clean Markdown. For non-HTML content (JSON, plain text), it returns the raw content with a content-type header.

Note

The Fetch Server respects robots.txt by default. If a site blocks automated access, the tool returns an error explaining the restriction and suggesting the user try the fetch prompt instead, which uses a different User-Agent string indicating user-directed access.

Prompt: fetch

The fetch prompt takes a url argument and returns the page content as a user message. Unlike the tool, the prompt uses a "User-Specified" User-Agent, indicating the fetch was explicitly requested by a human — which may satisfy sites that block autonomous agents.

Knowledge Graph (Memory)

The Memory Server stores entities, relations, and observations in a JSONL-backed knowledge graph.

Entity management:

Relation management:

Query tools:

Tip

search_nodes and open_nodes both return relations where at least one endpoint matches the result set, letting you discover connections to nodes outside your query.

Timezone Operations

The Time Server provides two tools:

Example — ask your assistant:

"What time is it in Tokyo right now?" "Convert 14:30 EST to Pacific time"

Sequential Thinking

The Sequential Thinking Server provides a single sequentialthinking tool for structured, multi-step reasoning.

This tool is designed for the AI assistant to use internally — you typically trigger it by asking for careful, step-by-step analysis of a complex problem.

5. Common Tasks

Read and Summarize a Project's Structure

"Show me the directory tree of /Users/me/project, excluding node_modules and .git"

The assistant uses directory_tree with excludePatterns: ["node_modules", ".git"] to get a recursive view of the project.

Review Recent Git Changes

"Show me what changed in the last week in /Users/me/project"

The assistant calls git_log with start_timestamp: "1 week ago", then uses git_show on interesting commits to see the full diffs.

Fetch and Analyze a Web Page

"Fetch the documentation at https://example.com/docs and summarize the key points"

The assistant calls fetch with the URL. If the page is larger than 5000 characters, it uses start_index to paginate through the content.

Build a Knowledge Graph from Research

1. Ask the assistant to create entities for key concepts:

   "Create entities for the main components of our system: API Gateway, Auth Service, Database"

2. Add relations between them:

   "The API Gateway routes to Auth Service, and Auth Service reads from Database"

3. Query the graph later:

   "Search the knowledge graph for everything related to 'Auth'"

Edit a Configuration File Safely

"In /Users/me/project/config.yaml, change the port from 3000 to 8080 — show me the diff first"

The assistant uses edit_file with dryRun: true first, then applies the change once you confirm.

Compare Files Across Branches

"Show me the diff between main and feature-branch in /Users/me/project"

The assistant calls git_diff with target: "main" from the feature branch.

Convert Meeting Times Across Time Zones

"I have a meeting at 10:00 AM in London. What time is that in New York and Tokyo?"

The assistant calls convert_time twice — once for each target timezone.

Stage, Commit, and Review in One Flow

"Stage all changes in /Users/me/project, commit with message 'Fix login bug', then show me the log"

The assistant chains git_add → git_commit → git_log sequentially.

Search for Files by Pattern

"Find all TypeScript test files in /Users/me/project"

The assistant uses search_files with pattern: "**/*.test.ts".

Get File Metadata Without Reading Content

"How large is /Users/me/data/export.csv and when was it last modified?"

The assistant calls get_file_info to retrieve size, timestamps, and permissions without reading the file content.

6. Troubleshooting

Server appears to hang when started directly

Cause: MCP servers communicate via stdio and wait for protocol messages. Running them in a terminal with no client attached causes them to block on stdin.

Solution:

1. Configure the server in your MCP client's configuration file
2. Let the client launch and manage the server process
3. If testing manually, pipe valid MCP JSON-RPC messages to stdin

Prevention: Always run MCP servers through an MCP client.

Error: Access denied - path outside allowed directories

Cause: The requested file path is not within any of the directories passed as arguments to the filesystem server.

Solution:

1. Check which directories are allowed using the list_allowed_directories tool
2. Ensure the file path is within one of the allowed directories
3. Add additional directories to the server's args in your config

Prevention: Configure all directories you need access to when setting up the server.

Error: Server cannot operate: No allowed directories available

Cause: The filesystem server was started without directory arguments and the MCP client does not support the roots protocol.

Solution:

1. Add at least one directory to the server's args array in your configuration
2. Or use an MCP client that supports the roots protocol

Error: Cannot specify both head and tail parameters simultaneously

Cause: A read_text_file call included both head and tail parameters.

Solution: Use either head to read from the beginning or tail to read from the end, not both.

Error: Could not find exact match for edit

Cause: The oldText in an edit_file operation doesn't match any content in the file. The match is exact (though whitespace-flexible on a per-line basis).

Solution:

1. Read the file first to see the exact current content
2. Copy the exact text you want to replace
3. Use dryRun: true to preview the edit before applying

Fetch tool returns robots.txt restriction error

Cause: The target website's robots.txt blocks the server's autonomous User-Agent.

Solution:

1. Use the fetch prompt instead of the tool — it uses a "User-Specified" User-Agent
2. Or configure the server with --ignore-robots-txt (use responsibly)
3. Or set a --custom-user-agent that the site allows

Warning

Using --ignore-robots-txt may violate the target site's terms of service. Use only for sites you own or have permission to access.

Fetch drops content from streaming/progressive rendering sites (GitHub Issue #3878)

Cause: Sites that use server-side rendering with progressive hydration may serve incomplete HTML that the readability extractor cannot process.

Solution:

1. Try fetching with raw: true to get the unprocessed HTML
2. If the site uses client-side JavaScript rendering, the content may not be available at all via simple HTTP fetch

Git server errors with InvalidGitRepositoryError

Cause: The repo_path does not point to a valid Git repository (no .git directory).

Solution:

1. Verify the path points to a directory containing a .git folder
2. Use an absolute path, not a relative one
3. If using --repository, ensure that argument points to a valid repo

MCP roots protocol overrides CLI-provided allowed directories (GitHub Issue #3929)

Cause: When the MCP client supports roots and provides root directories, the filesystem server replaces its CLI-configured allowed directories with the client-provided roots.

Solution:

1. Configure your allowed directories in your MCP client's roots instead of (or in addition to) CLI args
2. This is by-design behavior — the roots protocol takes precedence

Note

This behavior ensures the client controls which directories the server can access, which is the intended security model for the roots protocol.

Memory server: Entity with name X not found

Cause: add_observations was called with an entity name that doesn't exist in the knowledge graph.

Solution:

1. Create the entity first with create_entities
2. Then add observations to it

Prevention: Use search_nodes or read_graph to verify entity existence before adding observations.

Time server: Invalid timezone

Cause: The timezone name is not a valid IANA timezone identifier.

Solution: Use standard IANA names like America/New_York, Europe/London, Asia/Tokyo. Common mistakes include using abbreviations (EST, PST) instead of full IANA names.

7. FAQ

Q: Can I run multiple MCP servers at the same time?

Yes. Each server runs as an independent process. Configure as many as you need in your MCP client's config file — they operate independently and don't interfere with each other.

Q: Do the servers store any data or state?

Only the Memory Server persists state (to a JSONL file). The Sequential Thinking Server maintains thought history in memory for the duration of the session. All other servers are stateless — they perform operations and return results.

Q: Can I use the filesystem server with Docker?

Yes. Each server includes a Dockerfile. Mount your target directories as volumes and pass them as arguments. Note that paths inside the container must match the allowed directory arguments.

Q: What happens if the Memory Server's JSONL file gets corrupted?

The server reads each line independently. If a line contains invalid JSON, the server will throw an error on load. Back up the file regularly. The file format is one JSON object per line — entities and relations are stored as separate lines.

Q: Is the Everything Server meant for production use?

No. The Everything Server is a reference implementation designed to exercise and demonstrate every MCP protocol feature (tools, prompts, resources, subscriptions, logging, tasks, sampling, elicitation). Use it for testing MCP clients or learning the protocol.

Q: How does the filesystem server handle symbolic links?

The server resolves symlinks and validates that the resolved (real) path is within the allowed directories. This prevents symlink-based directory traversal attacks. On macOS, both the original and resolved paths are tracked (e.g., /tmp and /private/tmp).

Q: Can the Git server push to remote repositories?

No. The Git server provides local repository operations only — status, diff, commit, branch, log, checkout, and show. There are no push, pull, or remote management tools.

Q: What format does the Memory Server use for storage?

JSONL (JSON Lines). Each line is a JSON object with a type field ("entity" or "relation") and the corresponding data fields. The server automatically migrates from the legacy memory.json format to memory.jsonl on first run.

Q: Can I use relative paths with the filesystem server?

Yes. Relative paths are resolved against the first allowed directory. However, absolute paths are recommended to avoid ambiguity when multiple directories are configured.

Q: How do I check what the Sequential Thinking Server is doing?

Thought steps are logged to stderr by default. Watch the server's stderr output, or check your MCP client's server log viewer. Set DISABLE_THOUGHT_LOGGING=true to suppress this output.