Model Context Protocol Servers (modelcontextprotocol/servers)

Model Context Protocol Servers

https://github.com/modelcontextprotocol/servers
Admin
A collection of reference implementations and community-built servers for the Model Context...

Tokens:20,828
Snippets:84
Trust Score:7.8
Update:6 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# Model Context Protocol (MCP) Reference Servers

This repository contains a collection of reference implementations for the Model Context Protocol (MCP), a standardized protocol that enables Large Language Models (LLMs) to securely interact with external tools, data sources, and services. The MCP servers in this collection demonstrate how to build servers using official SDKs (TypeScript and Python), showcasing features like tools, prompts, resources, and bidirectional communication patterns.

The reference servers are designed as educational examples for developers building their own MCP integrations. Each server provides specific capabilities: filesystem operations with access control, web content fetching with robots.txt compliance, Git repository management, persistent knowledge graph memory, time/timezone utilities, and a comprehensive test server exercising all MCP protocol features. All servers can be run via NPX, Docker, or directly from source, and integrate seamlessly with Claude Desktop, VS Code, and other MCP-compatible clients.

---

## Filesystem Server - Read Text File

Reads the complete contents of a text file with optional head/tail line limiting. The server enforces directory access control through command-line arguments or dynamic MCP Roots.

```json
// Claude Desktop configuration (claude_desktop_config.json)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/allowed/directory"
      ]
    }
  }
}
```

```typescript
// MCP tool call example
{
  "name": "read_text_file",
  "arguments": {
    "path": "/Users/username/Desktop/config.json",
    "head": 50  // Optional: read first 50 lines only
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"name\": \"my-app\",\n  \"version\": \"1.0.0\",\n  ..."
    }
  ]
}
```

---

## Filesystem Server - Write File

Creates a new file or overwrites an existing file with the provided content. Uses atomic write operations to prevent race conditions and symlink attacks.

```typescript
// MCP tool call
{
  "name": "write_file",
  "arguments": {
    "path": "/Users/username/Desktop/output.txt",
    "content": "Hello, World!\nThis is line 2."
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Successfully wrote to /Users/username/Desktop/output.txt"
    }
  ]
}
```

---

## Filesystem Server - Edit File

Makes selective edits to files using pattern matching with whitespace normalization and indentation preservation. Supports dry-run mode to preview changes before applying.

```typescript
// MCP tool call with dry run
{
  "name": "edit_file",
  "arguments": {
    "path": "/Users/username/project/src/config.ts",
    "edits": [
      {
        "oldText": "const API_URL = 'http://localhost:3000';",
        "newText": "const API_URL = 'https://api.production.com';"
      },
      {
        "oldText": "const DEBUG = true;",
        "newText": "const DEBUG = false;"
      }
    ],
    "dryRun": true
  }
}

// Response (unified diff format)
{
  "content": [
    {
      "type": "text",
      "text": "```diff\n--- src/config.ts\n+++ src/config.ts\n@@ -1,4 +1,4 @@\n-const API_URL = 'http://localhost:3000';\n+const API_URL = 'https://api.production.com';\n const PORT = 8080;\n-const DEBUG = true;\n+const DEBUG = false;\n```"
    }
  ]
}
```

---

## Filesystem Server - Directory Tree

Returns a recursive JSON tree structure of directory contents with optional exclusion patterns using glob syntax.

```typescript
// MCP tool call
{
  "name": "directory_tree",
  "arguments": {
    "path": "/Users/username/project",
    "excludePatterns": ["node_modules/**", "*.log", ".git/**"]
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "[\n  {\n    \"name\": \"src\",\n    \"type\": \"directory\",\n    \"children\": [\n      { \"name\": \"index.ts\", \"type\": \"file\" },\n      { \"name\": \"utils.ts\", \"type\": \"file\" }\n    ]\n  },\n  { \"name\": \"package.json\", \"type\": \"file\" },\n  { \"name\": \"README.md\", \"type\": \"file\" }\n]"
    }
  ]
}
```

---

## Filesystem Server - Search Files

Recursively searches for files and directories matching glob patterns with exclusion support.

```typescript
// MCP tool call
{
  "name": "search_files",
  "arguments": {
    "path": "/Users/username/project",
    "pattern": "**/*.ts",
    "excludePatterns": ["**/*.test.ts", "node_modules/**"]
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "/Users/username/project/src/index.ts\n/Users/username/project/src/utils.ts\n/Users/username/project/src/types.ts"
    }
  ]
}
```

---

## Fetch Server - Fetch URL

Fetches web content and converts HTML to markdown for efficient LLM consumption. Supports pagination through start_index for large pages and respects robots.txt by default.

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

```typescript
// MCP tool call
{
  "name": "fetch",
  "arguments": {
    "url": "https://example.com/documentation",
    "max_length": 5000,
    "start_index": 0,
    "raw": false
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Contents of https://example.com/documentation:\n\n# Documentation\n\nWelcome to the documentation...\n\n<error>Content truncated. Call the fetch tool with a start_index of 5000 to get more content.</error>"
    }
  ]
}
```

```bash
# Run with custom options
uvx mcp-server-fetch --ignore-robots-txt --user-agent="CustomBot/1.0" --proxy-url="http://proxy:8080"
```

---

## Git Server - Repository Status and Diff

Provides comprehensive Git repository interaction including status, staging, commits, branches, and diffs with date filtering support.

```json
// Claude Desktop configuration
{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}
```

```typescript
// Get repository status
{
  "name": "git_status",
  "arguments": {
    "repo_path": "/Users/username/my-project"
  }
}

// View unstaged changes with context
{
  "name": "git_diff_unstaged",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "context_lines": 5
  }
}

// Stage specific files
{
  "name": "git_add",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "files": ["src/index.ts", "src/utils.ts"]
  }
}

// Create commit
{
  "name": "git_commit",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "message": "feat: add new utility functions"
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Committed with hash: a1b2c3d4e5f6..."
    }
  ]
}
```

---

## Git Server - Branch Operations and Log

Manages branches and retrieves commit history with flexible date filtering using ISO 8601, relative dates, or absolute date formats.

```typescript
// View commit log with date filtering
{
  "name": "git_log",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "max_count": 10,
    "start_timestamp": "2024-01-01",
    "end_timestamp": "2 weeks ago"
  }
}

// Create and checkout new branch
{
  "name": "git_create_branch",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "branch_name": "feature/new-feature",
    "base_branch": "main"
  }
}

// List branches containing specific commit
{
  "name": "git_branch",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "branch_type": "all",
    "contains": "a1b2c3d4"
  }
}

// Compare branches
{
  "name": "git_diff",
  "arguments": {
    "repo_path": "/Users/username/my-project",
    "target": "main",
    "context_lines": 3
  }
}
```

---

## Memory Server - Knowledge Graph Operations

Implements persistent memory using a local knowledge graph with entities, relations, and observations. Enables LLMs to remember information across chat sessions.

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

```typescript
// Create entities in the knowledge graph
{
  "name": "create_entities",
  "arguments": {
    "entities": [
      {
        "name": "John_Smith",
        "entityType": "person",
        "observations": ["Software engineer", "Speaks fluent Spanish", "Prefers morning meetings"]
      },
      {
        "name": "Anthropic",
        "entityType": "organization",
        "observations": ["AI safety company", "Founded in 2021"]
      }
    ]
  }
}

// Create relations between entities
{
  "name": "create_relations",
  "arguments": {
    "relations": [
      {
        "from": "John_Smith",
        "to": "Anthropic",
        "relationType": "works_at"
      }
    ]
  }
}

// Add observations to existing entity
{
  "name": "add_observations",
  "arguments": {
    "observations": [
      {
        "entityName": "John_Smith",
        "contents": ["Recently promoted to senior engineer", "Working on MCP project"]
      }
    ]
  }
}

// Search the knowledge graph
{
  "name": "search_nodes",
  "arguments": {
    "query": "engineer"
  }
}

// Retrieve specific nodes
{
  "name": "open_nodes",
  "arguments": {
    "names": ["John_Smith", "Anthropic"]
  }
}
```

---

## Time Server - Timezone Operations

Provides time queries and timezone conversions using IANA timezone names with automatic system timezone detection.

```json
// Claude Desktop configuration
{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}
```

```typescript
// Get current time in a timezone
{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Europe/London"
  }
}

// Response
{
  "timezone": "Europe/London",
  "datetime": "2024-06-15T14:30:00+01:00",
  "is_dst": true
}

// Convert time between timezones
{
  "name": "convert_time",
  "arguments": {
    "source_timezone": "America/New_York",
    "time": "09:00",
    "target_timezone": "Asia/Tokyo"
  }
}

// Response
{
  "source": {
    "timezone": "America/New_York",
    "datetime": "2024-06-15T09:00:00-04:00",
    "is_dst": true
  },
  "target": {
    "timezone": "Asia/Tokyo",
    "datetime": "2024-06-15T22:00:00+09:00",
    "is_dst": false
  },
  "time_difference": "+13.0h"
}
```

---

## Sequential Thinking Server - Problem Solving Tool

Facilitates structured, step-by-step thinking for complex problem-solving with support for revisions, branching, and dynamic thought adjustment.

```json
// Claude Desktop configuration
{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}
```

```typescript
// Initial thought in a sequence
{
  "name": "sequential_thinking",
  "arguments": {
    "thought": "First, let's understand the problem: we need to design a caching system for the API",
    "nextThoughtNeeded": true,
    "thoughtNumber": 1,
    "totalThoughts": 5
  }
}

// Revision of a previous thought
{
  "name": "sequential_thinking",
  "arguments": {
    "thought": "Actually, we should use Redis instead of in-memory caching for scalability",
    "nextThoughtNeeded": true,
    "thoughtNumber": 3,
    "totalThoughts": 6,
    "isRevision": true,
    "revisesThought": 2,
    "needsMoreThoughts": true
  }
}

// Branch into alternative reasoning path
{
  "name": "sequential_thinking",
  "arguments": {
    "thought": "Alternative approach: consider using CDN-level caching instead",
    "nextThoughtNeeded": true,
    "thoughtNumber": 4,
    "totalThoughts": 6,
    "branchFromThought": 2,
    "branchId": "cdn-approach"
  }
}
```

---

## Everything Server - MCP Protocol Test Server

A comprehensive test server that exercises all MCP protocol features including tools, prompts, resources, sampling, elicitation, and task management.

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

```bash
# Run with different transports
npx @modelcontextprotocol/server-everything stdio          # Default stdio transport
npx @modelcontextprotocol/server-everything sse            # HTTP+SSE transport
npx @modelcontextprotocol/server-everything streamableHttp # Streamable HTTP transport
```

```typescript
// Echo tool
{
  "name": "echo",
  "arguments": { "message": "Hello MCP!" }
}

// Get structured weather content
{
  "name": "get-structured-content",
  "arguments": { "location": "San Francisco" }
}
// Returns both backward-compatible content and structured JSON output

// Trigger long-running operation with progress
{
  "name": "trigger-long-running-operation",
  "arguments": {
    "duration": 10000,
    "steps": 5
  }
}

// Resource URIs available
// Dynamic text: demo://resource/dynamic/text/{index}
// Dynamic blob: demo://resource/dynamic/blob/{index}
// Static docs:  demo://resource/static/document/{filename}
// Session:      demo://resource/session/{name}
```

---

## VS Code MCP Configuration

All servers support VS Code integration through the MCP configuration system. Configuration can be added at user level or workspace level.

```json
// .vscode/mcp.json (Workspace configuration)
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}
```

---

## Docker Deployment

All servers are available as Docker images for containerized deployment with proper volume mounts for data persistence and sandboxing.

```bash
# Build Docker images
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
docker build -t mcp/memory -f src/memory/Dockerfile .
docker build -t mcp/git -f src/git/Dockerfile .
docker build -t mcp/fetch -f src/fetch/Dockerfile .
docker build -t mcp/time -f src/time/Dockerfile .
docker build -t mcp/sequentialthinking -f src/sequentialthinking/Dockerfile .
docker build -t mcp/everything -f src/everything/Dockerfile .
```

```json
// Docker configuration for Claude Desktop
{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/username/projects,dst=/projects",
        "mcp/filesystem", "/projects"
      ]
    },
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    },
    "git": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--mount", "type=bind,src=/Users/username,dst=/Users/username",
        "mcp/git"
      ]
    }
  }
}
```

---

## Debugging with MCP Inspector

Use the MCP Inspector to debug and test server implementations interactively.

```bash
# Debug installed servers
npx @modelcontextprotocol/inspector uvx mcp-server-fetch
npx @modelcontextprotocol/inspector uvx mcp-server-git
npx @modelcontextprotocol/inspector uvx mcp-server-time

# Debug from source
cd src/fetch && npx @modelcontextprotocol/inspector uv run mcp-server-fetch
cd src/filesystem && npx @modelcontextprotocol/inspector npx ts-node index.ts /tmp

# View Claude Desktop logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```

---

The MCP reference servers provide a comprehensive foundation for building LLM-integrated applications. Primary use cases include: AI-assisted file management and code editing with access controls, automated Git workflows for version control, persistent memory systems for personalized AI assistants, web content extraction for research tasks, timezone-aware scheduling, and structured problem-solving frameworks. Each server demonstrates best practices for security (path validation, symlink protection, atomic operations), error handling, and protocol compliance.

Integration patterns follow a consistent approach: configure servers in client settings (Claude Desktop, VS Code, or custom MCP clients), invoke tools through the standardized MCP protocol, and handle responses including text content, resources, and structured data. The servers support multiple transport mechanisms (stdio, HTTP+SSE, Streamable HTTP) for flexible deployment scenarios. Developers can use these reference implementations as templates for building custom MCP servers that extend LLM capabilities with domain-specific tools and data access.