# 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):

```bash
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

| Requirement | TypeScript Servers | Python Servers |
|---|---|---|
| Runtime | Node.js 18+ | Python 3.10+ |
| Package manager | npm 9+ | `uv` (recommended) or `pip` |
| OS | Linux, macOS, Windows | Linux, macOS, Windows |
| Git | — | Required (system install) for Git server |

### Installing TypeScript Servers

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

| Package | Binary | Purpose |
|---|---|---|
| `@modelcontextprotocol/server-filesystem` | `mcp-server-filesystem` | Secure filesystem access |
| `@modelcontextprotocol/server-memory` | `mcp-server-memory` | Knowledge graph persistence |
| `@modelcontextprotocol/server-sequential-thinking` | `mcp-server-sequential-thinking` | Structured reasoning |
| `@modelcontextprotocol/server-everything` | `mcp-server-everything` | Reference/demo server |

=== "npx (no install)"
    ```bash
    npx -y @modelcontextprotocol/server-filesystem /path/to/directory
    ```

=== "Global install"
    ```bash
    npm install -g @modelcontextprotocol/server-filesystem
    mcp-server-filesystem /path/to/directory
    ```

=== "From source"
    ```bash
    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:

| Package | Module | Purpose |
|---|---|---|
| `mcp-server-fetch` | `mcp_server_fetch` | Web content fetching |
| `mcp-server-git` | `mcp_server_git` | Git repository operations |
| `mcp-server-time` | `mcp_server_time` | Timezone queries |

=== "uvx (no install)"
    ```bash
    uvx mcp-server-fetch
    ```

=== "pip install"
    ```bash
    pip install mcp-server-fetch
    python -m mcp_server_fetch
    ```

### Post-Install Verification

Verify a TypeScript server:

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

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

Verify a Python server:

```bash
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:

| Client | Config File |
|---|---|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| VS Code | `.vscode/mcp.json` in your workspace |
| Cursor | `.cursor/mcp.json` in your workspace |

### Filesystem Server Configuration

```json
{
  "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

```json
{
  "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

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

Optional arguments:

| Argument | Description |
|---|---|
| `--custom-user-agent` | Override the default User-Agent string |
| `--ignore-robots-txt` | Skip robots.txt checks (use responsibly) |
| `--proxy-url` | Route requests through an HTTP proxy |

### Memory Server Configuration

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

| Environment Variable | Default | Description |
|---|---|---|
| `MEMORY_FILE_PATH` | `memory.jsonl` in the server's directory | Path to the knowledge graph storage file |

> [!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

```json
{
  "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

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

| Environment Variable | Default | Description |
|---|---|---|
| `DISABLE_THOUGHT_LOGGING` | `false` | Set to `true` to suppress thought output to stderr |

### Everything Server Configuration

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

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

| Transport | Argument | Use Case |
|---|---|---|
| stdio | `stdio` (default) | Standard MCP client integration |
| SSE | `sse` | Server-Sent Events over HTTP |
| Streamable HTTP | `streamableHttp` | Bidirectional HTTP streaming |

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:**

| Tool | Purpose | Key Parameters |
|---|---|---|
| `read_text_file` | Read a single file as text | `path`, optional `head` or `tail` (line count) |
| `read_media_file` | Read images/audio as base64 | `path` |
| `read_multiple_files` | Batch-read multiple files | `paths` (array) |

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:**

| Tool | Purpose | Key Parameters |
|---|---|---|
| `write_file` | Create or overwrite a file | `path`, `content` |
| `edit_file` | Find-and-replace edits with diff preview | `path`, `edits` (array of `{oldText, newText}`), `dryRun` |

> [!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:**

| Tool | Purpose |
|---|---|
| `list_directory` | List entries with `[FILE]`/`[DIR]` prefixes |
| `list_directory_with_sizes` | Same as above, with file sizes and optional sorting by `name` or `size` |
| `directory_tree` | Recursive JSON tree structure with `excludePatterns` support |
| `create_directory` | Create directories recursively |
| `move_file` | Move or rename files/directories |
| `search_files` | Glob-pattern search across directory trees |
| `get_file_info` | File metadata (size, timestamps, permissions) |
| `list_allowed_directories` | Show which directories the server can access |

> [!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):**

| Tool | Description | Key Parameters |
|---|---|---|
| `git_status` | Working tree status | `repo_path` |
| `git_diff_unstaged` | Unstaged changes | `repo_path`, `context_lines` (default: 3) |
| `git_diff_staged` | Staged changes | `repo_path`, `context_lines` |
| `git_diff` | Diff against a branch or commit | `repo_path`, `target`, `context_lines` |
| `git_log` | Commit history | `repo_path`, `max_count`, `start_timestamp`, `end_timestamp` |
| `git_show` | Show commit contents with patch | `repo_path`, `revision` |
| `git_branch` | List branches | `repo_path`, `branch_type` (`local`/`remote`/`all`), `contains`, `not_contains` |

**Mutation tools:**

| Tool | Description | Key Parameters |
|---|---|---|
| `git_add` | Stage files | `repo_path`, `files` (array; use `["."]` for all) |
| `git_commit` | Commit staged changes | `repo_path`, `message` |
| `git_create_branch` | Create a new branch | `repo_path`, `branch_name`, optional `base_branch` |
| `git_checkout` | Switch branches | `repo_path`, `branch_name` |
| `git_reset` | Unstage all staged changes | `repo_path` |

> [!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`**

| Parameter | Type | Default | Description |
|---|---|---|---|
| `url` | string | (required) | URL to fetch |
| `max_length` | integer | 5000 | Maximum characters to return |
| `start_index` | integer | 0 | Character offset for pagination |
| `raw` | boolean | false | Return raw HTML instead of Markdown |

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:**

| Tool | Description |
|---|---|
| `create_entities` | Create entities with `name`, `entityType`, and `observations` |
| `delete_entities` | Remove entities and their associated relations |
| `add_observations` | Append observations to existing entities |
| `delete_observations` | Remove specific observations from entities |

**Relation management:**

| Tool | Description |
|---|---|
| `create_relations` | Create directed relations (`from` → `to` with `relationType`) |
| `delete_relations` | Remove specific relations |

**Query tools:**

| Tool | Description |
|---|---|
| `read_graph` | Return the entire knowledge graph |
| `search_nodes` | Search entities by name, type, or observation content |
| `open_nodes` | Retrieve specific entities by name with their relations |

> [!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:

| Tool | Description | Parameters |
|---|---|---|
| `get_current_time` | Current time in a timezone | `timezone` (IANA name) |
| `convert_time` | Convert between timezones | `source_timezone`, `time` (HH:MM, 24h), `target_timezone` |

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.

| Parameter | Type | Description |
|---|---|---|
| `thought` | string | Current thinking step |
| `nextThoughtNeeded` | boolean | Whether more thinking is needed |
| `thoughtNumber` | integer | Current step number |
| `totalThoughts` | integer | Estimated total steps (adjustable) |
| `isRevision` | boolean | Whether this revises a previous thought |
| `revisesThought` | integer | Which thought number is being revised |
| `branchFromThought` | integer | Branching point for alternative reasoning |
| `branchId` | string | Identifier for the current branch |
| `needsMoreThoughts` | boolean | Signal that more thoughts are needed beyond the estimate |

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.

---

_Generated May 2026 from modelcontextprotocol/servers at 4503e2d. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._