Related Pages

Related topics: Repository Structure, Quick Start Guide

Home

Overview

The Model Context Protocol (MCP) Servers repository is the official collection of reference implementations for MCP servers. MCP is a protocol that enables AI models to interact with external tools, resources, and data sources through a standardized interface.

This repository serves as a central hub for developing, documenting, and distributing MCP server implementations that can be integrated with AI assistants and development tools.

Sources: CLAUDE.md:1

Repository Architecture

The repository follows a monorepo structure where each MCP server resides in its own directory under src/.

graph TD
    A[Model Context Protocol Servers] --> B[fetch]
    A --> C[sequential-thinking]
    A --> D[everything]
    A --> E[filesystem]
    A --> F[time]
    A --> G[memory]
    
    H[Shared Infrastructure] --> A
    H --> I[CLAUDE.md Guidelines]
    H --> J[Contributing Standards]

Available MCP Servers

Server Comparison Table

Sources: src/fetch/README.md, src/everything/README.md

Fetch Server

The fetch server provides HTTP content retrieval capabilities with support for:

• Web content fetching via tools
• User-initiated requests
• robots.txt compliance (configurable)
• Custom user-agent headers
• Proxy support

Installation Methods:

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

Sources: src/fetch/README.md:1-50

Filesystem Server

The filesystem server exposes file system operations with security boundaries:

• Read operations: read_file, read_media_file, read_multiple_files
• Directory operations: list_directory, directory_tree, search_files
• Write operations: create_directory, write_file, edit_file, move_file
• All paths validated against allowed directories

File Operation Annotations:

Sources: src/filesystem/README.md

Memory Server

The memory server implements a knowledge graph for persistent entity storage:

• create_entities: Create new entities with type classification
• create_relations: Establish relationships between entities
• add_observations: Append observations to existing entities
• delete_entities: Remove entities and cascading relations
• delete_observations: Remove specific observations

Storage backend: JSONL file format (configurable via MEMORY_FILE_PATH)

Sources: src/memory/README.md

Time Server

The time server provides timezone-aware time utilities:

• Get current time in any timezone
• Convert times between timezones
• Automatic system timezone detection
• Configurable via --local-timezone argument

Sources: src/time/README.md

Everything Server

The everything server aggregates multiple MCP capabilities into a single server. Supports multiple transport protocols:

• stdio (default)
• SSE (deprecated as of 2025-03-26)
• Streamable HTTP

Sources: src/everything/README.md

Development Standards

TypeScript Servers

Code Style Guidelines:

• ES modules with .js extension in import paths
• Zod schemas for tool input validation
• 2-space indentation, trailing commas in multi-line objects
• camelCase for variables/functions, PascalCase for types/classes
• kebab-case for file names and registered tools/prompts/resources
• Verb-first tool names (e.g., get-file-info)

Sources: CLAUDE.md:5-15

Python Servers

Development Commands:

cd src/<server> && uv sync --frozen --all-extras --dev
uv run pytest
uv run pyright
uv run ruff check .

Sources: CLAUDE.md:16-26

Contributing

Accepted Contributions

• Bug fixes
• Usability improvements
• Enhancements demonstrating MCP protocol features (Resources, Prompts, Roots)

Testing Requirements

All new functionality requires corresponding tests under tests/ or test/ directories.

Code Review

• Pull requests welcome
• CI enforces type checking and linting standards

Sources: CLAUDE.md:27-35

Client Integration

Claude Desktop

Add server configurations to claude_desktop_config.json:

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

VS Code

One-click installation buttons available in each server's README for quick setup.

Zed

Configuration via settings.json using the context_servers array format.

Docker Installation

All servers support Docker deployment:

{
  "mcpServers": {
    "server-name": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/server-name"]
    }
  }
}

Debugging

Use the MCP Inspector for debugging:

# For uvx installations
npx @modelcontextprotocol/inspector uvx mcp-server-fetch

# For local development
cd path/to/servers/src/<server>
npx @modelcontextprotocol/inspector uv run mcp-server-<server>

Sources: src/fetch/README.md:1

License

All MCP servers in this repository are licensed under the MIT License, permitting free use, modification, and distribution subject to MIT License terms.

Related Pages

Related topics: Home, Quick Start Guide

Repository Structure

Overview

The modelcontextprotocol/servers repository is a monorepo containing implementations of Model Context Protocol (MCP) servers. MCP is a protocol that enables AI models to interact with external tools, resources, and data sources. The repository houses multiple independent server implementations, each providing different capabilities such as filesystem access, web fetching, time utilities, and more.

The repository supports two primary implementation languages: TypeScript/Node.js and Python. This dual-language approach allows developers to choose their preferred runtime environment while maintaining feature parity across servers.

Directory Layout

The repository follows a modular structure where each MCP server lives in its own directory under the src/ prefix.

servers/
├── package.json              # Root workspace configuration
├── tsconfig.json              # TypeScript configuration
├── CLAUDE.md                  # Developer guidelines
├── .github/                   # GitHub workflows and PR templates
├── src/
│   ├── everything/            # Multi-feature demonstration server (TypeScript)
│   ├── filesystem/            # File operations server (TypeScript)
│   ├── fetch/                 # Web content fetching server (Python)
│   ├── memory/                # Knowledge graph memory server (TypeScript)
│   ├── sequentialthinking/    # Chain-of-thought reasoning server (TypeScript)
│   └── time/                  # Time utilities server (Python)

Each server directory is self-contained with its own dependencies, build configuration, and documentation. The src/everything server serves as a reference implementation demonstrating all MCP capabilities including tools, resources, and prompts.

Technology Stack

TypeScript Servers

TypeScript-based servers use the following technology stack:

Sources: CLAUDE.md:2-8

The TypeScript servers share common patterns:

• ES Modules with .js extension in import paths
• Strict TypeScript typing for all functions and variables
• Zod schemas for tool input validation
• 2-space indentation with trailing commas
• Naming conventions: camelCase for variables/functions, PascalCase for types/classes, kebab-case for file names and registered tools/prompts/resources

Sources: CLAUDE.md:24-30

Python Servers

Python servers follow these specifications:

Sources: CLAUDE.md:10-17

Python server development commands follow a consistent pattern:

cd src/<server> && uv sync --frozen --all-extras --dev
uv run pytest      # Run tests
uv run pyright     # Type checking
uv run ruff check .  # Linting

Sources: CLAUDE.md:12-16

Server Organization

Server Categories

The servers in this repository can be categorized by their implementation language and primary function:

graph TD
    A[modelcontextprotocol/servers] --> B[TypeScript Servers]
    A --> C[Python Servers]
    
    B --> B1[everything]
    B --> B2[filesystem]
    B --> B3[memory]
    B --> B4[sequentialthinking]
    
    C --> C1[fetch]
    C --> C2[time]
    
    B1 --> B1a[Tools, Resources, Prompts]
    B2 --> B2a[File Operations]
    B3 --> B3a[Knowledge Graph]
    B4 --> B4a[Chain-of-Thought]
    C1 --> C1a[HTTP Fetching]
    C2 --> C2a[Timezone Operations]

TypeScript Server Structure

Each TypeScript server follows a consistent internal structure:

src/<server-name>/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts           # Main entry point
│   ├── tools/              # Tool definitions
│   ├── resources/          # Resource definitions
│   ├── prompts/            # Prompt templates
│   └── types/              # TypeScript type definitions
├── docs/                   # Server documentation
└── tests/                  # Test files

Sources: CLAUDE.md:35-37

The modular structure allows each server to register its capabilities through standardized functions:

• registerTools(server) - Register MCP tools
• registerResources(server) - Register MCP resources
• registerPrompts(server) - Register MCP prompts

Sources: CLAUDE.md:41-43

Python Server Structure

Python servers use pyproject.toml for configuration and follow this pattern:

src/<server-name>/
├── pyproject.toml          # Project metadata and dependencies
├── src/
│   └── mcp_server_<name>/  # Package directory
│       ├── __init__.py
│       └── server.py       # Main server implementation
└── tests/                  # Test files

Sources: src/fetch/pyproject.toml

Configuration Patterns

Claude Desktop Integration

Servers can be integrated with Claude Desktop through JSON configuration. Each server provides installation instructions for different deployment methods.

#### NPX Installation (Node.js servers)

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

Sources: src/filesystem/README.md:1-10

#### UVX Installation (Python servers)

{
  "mcpServers": {
    "server-name": {
      "command": "uvx",
      "args": ["mcp-server-<name>"]
    }
  }
}

Sources: src/fetch/README.md:1-8

#### Docker Installation

{
  "mcpServers": {
    "server-name": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/<server-name>"]
    }
  }
}

Sources: src/everything/README.md:1-10

Windows Configuration

Windows environments require cmd /c wrapper for NPX commands:

{
  "servers": {
    "server-name": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-<name>"]
    }
  }
}

Sources: src/filesystem/README.md:1-20

Windows users running Python servers via UVX may need to set environment variables to avoid timeout issues:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Sources: src/fetch/README.md:1-15

Build and Development

Building Docker Images

Each server can be containerized for deployment:

docker build -t mcp/<server-name> -f src/<server-name>/Dockerfile .

Sources: src/filesystem/README.md:1-5

For the everything server:

docker build -t mcp/everything -f src/everything/Dockerfile .

Running from Source

#### TypeScript Servers

cd src/<server>
npm install
npm run start:streamableHttp  # Streamable HTTP transport
npm run start:sse             # SSE transport (deprecated)

Sources: src/everything/README.md:1-15

#### Python Servers

cd src/<server>
uv sync --frozen --all-extras --dev
uv run mcp-server-<name>

Debugging

The MCP Inspector tool can be used to debug servers:

npx @modelcontextprotocol/inspector uvx mcp-server-<name>

Sources: src/fetch/README.md:1-5

For local development:

cd path/to/servers/src/<server>
npx @modelcontextprotocol/inspector uv run mcp-server-<name>

Contributing Patterns

Adding New Servers

The repository provides clear guidelines for extending the project:

1. Create a new directory under src/<server-name>/
2. Follow the established patterns for your implementation language
3. Implement server capability registration functions
4. Add comprehensive documentation

Key Contributing Guidelines

Sources: CLAUDE.md:41-46

Everything Server as Reference

The src/everything server demonstrates all MCP features and is an excellent reference for implementing new servers:

• Modular structure: Separate modules for tools, resources, and prompts
• Registration pattern: registerX(server) functions following SDK conventions
• Schema accuracy: JSON Schema with descriptions and examples
• Extensibility: Easy to add new modules following existing patterns

Sources: src/everything/AGENTS.md:1-8

Transport Protocols

The repository supports multiple transport mechanisms for client-server communication:

Sources: src/everything/README.md:1-20

The streamable HTTP transport is the recommended modern approach:

npx @modelcontextprotocol/server-<name> streamableHttp

Tool Annotation System

TypeScript servers use a standardized annotation system for tools to indicate their behavior to clients:

Sources: src/filesystem/README.md:1-30

Example from the filesystem server:

server.registerTool(
  "write_file",
  {
    title: "Write File",
    inputSchema: {
      path: z.string(),
      content: z.string()
    },
    annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: true }
  },
  async (args) => { /* ... */ }
);

Sources: src/filesystem/index.ts:1-25

Summary

The modelcontextprotocol/servers repository is organized as a well-structured monorepo that:

• Contains multiple independent MCP server implementations under src/
• Supports both TypeScript (Node.js 22) and Python (>=3.10) implementations
• Follows consistent patterns for tool, resource, and prompt registration
• Provides flexible deployment options (NPX, UVX, Docker)
• Includes comprehensive documentation and debugging tools
• Enforces type safety and testing through CI/CD

The everything server serves as the primary reference implementation, while other servers demonstrate specialized use cases like filesystem operations, web fetching, time utilities, and knowledge graph storage.

Related Pages

Related topics: Home, Everything Server

Quick Start Guide

This guide provides a comprehensive introduction to getting started with Model Context Protocol (MCP) servers. MCP servers are tools that extend the capabilities of AI assistants like Claude by providing access to external resources, file systems, databases, and more.

Overview

The MCP servers repository contains a collection of standalone servers that implement the Model Context Protocol. Each server provides specific functionality that can be integrated into MCP-compatible clients such as Claude Desktop, VS Code, and Zed.

graph TD
    A[MCP Client] --> B[MCP Server]
    B --> C[Git Server]
    B --> D[Memory Server]
    B --> E[Filesystem Server]
    B --> F[Fetch Server]
    B --> G[Time Server]
    B --> H[Everything Server]
    B --> I[Sequential Thinking Server]

Prerequisites

Before getting started with MCP servers, ensure your environment meets the following requirements.

System Requirements

Required Tools

Based on the project guidelines, the following tools are required:

• For Python servers: uv is the primary package manager Sources: CLAUDE.md
• For Node.js servers: npm or npx Sources: README.md
• For containerized deployment: Docker

Installation Methods

MCP servers support multiple installation methods. Choose the one that best fits your environment.

Method 1: Using uvx (Recommended)

uvx is the recommended installation method for Python-based servers. It provides easy setup and automatic dependency management Sources: README.md

# Install a single server
uvx mcp-server-git

# Or install via npm for quick testing
npx @modelcontextprotocol/server-memory

Method 2: Using pip

For Python servers, you can also use pip directly:

# Install the server package
pip install mcp-server-git

# Run the server
python -m mcp_server_git

Method 3: Using Docker

Docker provides isolation and consistency across different environments:

# Pull and run a pre-built image
docker run -i --rm mcp/filesystem

# Build your own image
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Method 4: Using npx (Node.js)

For TypeScript/JavaScript servers:

# Run directly with npx
npx -y @modelcontextprotocol/server-memory

Quick Start by Server Type

Git Server

The Git server provides tools for interacting with Git repositories.

Installation:

uvx mcp-server-git

Alternative with pip:

pip install mcp-server-git
python -m mcp_server_git

Sources: README.md

Memory Server

The Memory server provides a knowledge graph storage system for maintaining persistent context across conversations Sources: src/memory/README.md

Installation:

npx -y @modelcontextprotocol/server-memory

Custom Configuration:

Example Configuration:

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

Filesystem Server

The Filesystem server provides secure file system access within allowed directories Sources: src/filesystem/README.md

Installation:

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

Available Tools:

Fetch Server

The Fetch server enables web content retrieval with proper robots.txt compliance Sources: src/fetch/README.md

Installation:

uvx mcp-server-fetch

Customization Options:

Default User-Agents:

ModelContextProtocol/1.0 (Autonomous; +https://github.com/modelcontextprotocol/servers)
ModelContextProtocol/1.0 (User-Specified; +https://github.com/modelcontextprotocol/servers)

Time Server

The Time server provides timezone-aware time operations Sources: src/time/README.md

Installation:

uvx mcp-server-time

Available Tools:

Example Request:

{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Europe/Warsaw"
  }
}

Sequential Thinking Server

The Sequential Thinking server provides structured reasoning capabilities Sources: src/sequentialthinking/README.md

Installation:

npx -y @modelcontextprotocol/server-sequential-thinking

Building from Source:

docker build -t mcp/sequentialthinking -f src/sequentialthinking/Dockerfile .

Everything Server

The Everything server aggregates multiple MCP server capabilities into a single endpoint Sources: src/everything/README.md

Installation:

npx -y @modelcontextprotocol/server-everything

Available Transport Options:

Client Configuration

Claude Desktop Configuration

Add server configurations to your Claude Desktop settings file Sources: README.md:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Windows Configuration

On Windows, wrap commands with cmd /c:

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

VS Code Configuration

Quick installation buttons are available for VS Code and VS Code Insiders. Simply click the badge to install:

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

Zed Configuration

"context_servers": {
  "mcp-server-time": {
    "command": "uvx",
    "args": ["mcp-server-time"]
  }
}

Development Setup

Setting Up Python Server Development

cd src/<server> && uv sync --frozen --all-extras --dev

# Run tests
uv run pytest

# Type checking
uv run pyright

# Linting
uv run ruff check .

Sources: CLAUDE.md

Setting Up Node.js Server Development

cd src/<server>
npm install
npm run build

Testing:

npm test

Troubleshooting

Common Issues

#### Timeout Issues on Windows

If experiencing timeout issues on Windows, set the PYTHONIOENCODING environment variable:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

#### Character Encoding Issues

For servers that handle text content, ensure proper encoding by adding environment variables or command-line arguments as shown above.

Debugging with MCP Inspector

Use the MCP inspector to debug server functionality:

# For uvx installations
npx @modelcontextprotocol/inspector uvx mcp-server-fetch

# For local development
cd path/to/servers/src/fetch
npx @modelcontextprotocol/inspector uv run mcp-server-fetch

Architecture Overview

graph LR
    A[Client Application] -->|MCP Protocol| B[Transport Layer]
    B -->|stdio/sse/http| C[Server Implementation]
    C -->|Tool Execution| D[External Resources]
    D -->|Results| C
    C -->|Formatted Response| B
    B -->|MCP Response| A

Transport Methods

Next Steps

• Explore individual server documentation for advanced features
• Review the CLAUDE.md for contribution guidelines
• Check the main README.md for the complete server list
• Join the community to share your implementations and extensions

Related Pages

Related topics: Filesystem Server, Memory Server

Everything Server

Overview

The Everything Server is a comprehensive Model Context Protocol (MCP) server implementation that provides a wide range of tools, resources, and prompts for AI-assisted interactions. It serves as a reference implementation demonstrating the full capabilities of the MCP specification. Sources: src/everything/README.md

Purpose and Scope

The Everything Server is designed to:

• Provide a complete example of MCP server implementation patterns
• Offer practical tools for file system operations, memory management, and more
• Demonstrate resource and prompt template capabilities
• Support multiple transport mechanisms for different use cases
• Serve as a foundation for building custom MCP servers Sources: src/everything/AGENTS.md

Architecture

High-Level Architecture

graph TD
    A[Client] -->|MCP Protocol| B[Transport Layer]
    B --> C[stdio]
    B --> D[SSE]
    B --> E[Streamable HTTP]
    C --> F[Server Core]
    D --> F
    E --> F
    F --> G[Tools Handler]
    F --> H[Resources Handler]
    F --> I[Prompts Handler]
    G --> J[File System Tools]
    G --> K[Memory Tools]
    G --> L[Utility Tools]
    H --> M[Static Resources]
    H --> N[Dynamic Resources]
    I --> O[Prompt Templates]

Module Structure

The server is organized into distinct modules following a clear separation of concerns: Sources: src/everything/docs/architecture.md

Component Hierarchy

graph TD
    A[McpServer Instance] --> B[Tools Registry]
    A --> C[Resources Registry]
    A --> D[Prompts Registry]
    B --> E[Tool Handlers]
    C --> F[Resource Providers]
    D --> G[Prompt Definitions]
    E --> H[File Operations]
    E --> I[Memory Operations]
    E --> J[Utility Operations]

Installation

Prerequisites

• Node.js version 22 or higher
• npm or npx for package management Sources: CLAUDE.md

Installation Methods

#### Global npm Installation

npm install -g @modelcontextprotocol/server-everything@latest

#### Using npx (No Installation Required)

npx @modelcontextprotocol/server-everything

#### Docker

docker run -i --rm mcp/everything

#### Running from Source

cd src/everything
npm install
npm run start:streamableHttp

Sources: src/everything/README.md

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

#### Windows Configuration

On Windows, use cmd /c for proper process handling:

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

Transport Options

The Everything Server supports multiple transport mechanisms for communication with MCP clients.

Supported Transports

Running with Different Transports

# Default (stdio)
npx @modelcontextprotocol/server-everything

# Explicitly stdio
npx @modelcontextprotocol/server-everything stdio

# SSE (deprecated)
npx @modelcontextprotocol/server-everything sse

# Streamable HTTP (recommended)
npx @modelcontextprotocol/server-everything streamableHttp

Sources: src/everything/README.md

Features

Core Capabilities

The Everything Server provides a comprehensive set of features: Sources: src/everything/docs/features.md

• Tool Orchestration: Extensive set of tools for various operations
• Resource Management: Static and dynamic resource provision
• Prompt Templates: Reusable prompt definitions
• Session Resources: Dynamic session-based resource creation
• Multi-Transport Support: stdio, HTTP+SSE, and Streamable HTTP

Tool Categories

Tools Reference

Tool Registration Pattern

Tools are registered using the MCP SDK with Zod schemas for input validation: Sources: src/everything/tools/index.ts

server.registerTool(
  "tool_name",
  {
    title: "Tool Title",
    description: "Tool description",
    inputSchema: { /* Zod schema */ },
    outputSchema: { /* output schema */ },
    annotations: {
      readOnlyHint: boolean,
      idempotentHint: boolean,
      destructiveHint: boolean
    }
  },
  async (args) => {
    // Handler implementation
  }
);

Tool Annotations

Each tool includes annotations describing its behavior: Sources: src/filesystem/README.md

Resources

Resource Types

The Everything Server implements resources following the MCP specification: Sources: src/everything/resources/index.ts

graph LR
    A[Resources] --> B[Static Resources]
    A --> C[Dynamic Resources]
    A --> D[Session Resources]
    B --> E[Pre-registered at startup]
    C --> F[Generated on-demand]
    D --> G[Created per session]

Session Resources

Session resources are dynamically created and managed: Sources: src/everything/resources/session.ts:1-65

export const registerSessionResource = (
  server: McpServer,
  resource: Resource,
  type: "text" | "blob",
  payload: string
): ResourceLink => {
  // Prepare resource content based on type
  const resourceContent = type === "text"
    ? { uri: uri.toString(), mimeType, text: payload }
    : { uri: uri.toString(), mimeType, blob: payload };

  // Remove existing resource with same URI if present
  const existingResource = registeredResources.get(uri);
  if (existingResource) {
    existingResource.remove();
    registeredResources.delete(uri);
  }

  // Register the resource with the server
  const registeredResource = server.registerResource(
    name, uri,
    { mimeType, description, title, annotations, icons, _meta },
    async () => ({ contents: [resourceContent] })
  );

  registeredResources.set(uri, registeredResource);
  return { type: "resource_link", ...resource };
};

Extension Guide

Adding New Tools

To extend the Everything Server with new tools: Sources: src/everything/docs/extension.md

1. Create a new file in the tools/ folder (naming, exports, and registration function)
2. Export a registerX(server) function that registers new items with the MCP SDK
3. Wire your new module into the central index (tools/index.ts)
4. Ensure schemas are accurate JSON Schema with helpful descriptions and examples

Extension Pattern

// tools/example-tool.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerExampleTool(server: McpServer): void {
  server.registerTool(
    "example_tool",
    {
      title: "Example Tool",
      description: "An example tool demonstrating the extension pattern",
      inputSchema: {
        param: z.string().describe("Example parameter")
      },
      outputSchema: { result: z.string() }
    },
    async (args) => {
      // Implementation
      return { content: [{ type: "text", text: result }] };
    }
  );
}

Updating Documentation

Keep the documentation in src/everything/docs/ up to date when adding or modifying features. Sources: src/everything/AGENTS.md

Configuration

Environment Variables

Claude Desktop Configuration Example

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

Development

Project Structure

src/everything/
├── index.ts                 # Main entry point
├── server/
│   └── index.ts            # Server configuration
├── tools/
│   ├── index.ts            # Tool registry
│   └── *.ts                # Individual tool implementations
├── resources/
│   ├── index.ts            # Resource registry
│   └── session.ts          # Session resource management
├── prompts/
│   └── index.ts            # Prompt templates
└── docs/
    ├── features.md         # Feature documentation
    ├── architecture.md     # Architecture details
    └── extension.md        # Extension guide

Build Requirements

• Runtime: Node.js 22
• Target: ES2022
• Module: Node16
• Type Checking: Strict TypeScript mode
• Testing: vitest with @vitest/coverage-v8 Sources: CLAUDE.md

Code Style Guidelines

#### TypeScript Standards

• ES modules with .js extension in import paths
• Strict TypeScript typing for all functions and variables
• Zod schemas for tool input validation
• 2-space indentation with trailing commas
• camelCase for variables/functions, PascalCase for types/classes
• kebab-case for file names and registered tools/prompts/resources
• Verb-first tool names (e.g., get-file-info, not file-info) Sources: CLAUDE.md

Troubleshooting

Common Issues

Debugging

Use the MCP inspector for debugging:

cd src/everything
npx @modelcontextprotocol/inspector

License

The Everything Server is licensed under the MIT License. You are free to use, modify, and distribute the software subject to the terms and conditions of the MIT License. Sources: src/everything/README.md

See Also

• MCP Specification
• MCP Servers Repository
• MCP SDK Documentation

Related Pages

Related topics: Everything Server, Git Server

Filesystem Server

The Filesystem Server is an MCP (Model Context Protocol) server implementation that provides secure file system access capabilities to AI models and clients. It enables reading, writing, and managing files and directories within configurable sandboxed environments, with comprehensive security controls through path validation and access restrictions.

Overview

The Filesystem Server bridges AI assistants with the local file system by exposing a standardized set of tools that perform file operations. All operations are scoped to user-defined allowed directories, preventing unauthorized access to system files or sensitive locations.

Key Characteristics:

Sources: src/filesystem/README.md:1-10

Architecture

graph TD
    A[MCP Client] -->|MCP Protocol| B[Filesystem Server]
    B --> C[Tool Handlers]
    C --> D[Path Validation Layer]
    D --> E[Allowed Directories]
    D --> F[File System Operations]
    F --> G[read_text_file]
    F --> H[write_file]
    F --> I[create_directory]
    F --> J[move_file]
    F --> K[list_directory]
    F --> L[search_files]
    E --> M[Security Boundaries]

Core Components

Sources: src/filesystem/index.ts:1-50

Tool Specifications

Read Operations

All read tools have readOnlyHint: true annotation, indicating they do not modify system state.

Sources: src/filesystem/README.md:15-30

Write Operations

Sources: src/filesystem/README.md:32-40

Annotation Semantics

graph LR
    A[readOnlyHint] --> B{true?}
    B -->|Yes| C[Read operations<br/>No state changes]
    B -->|No| D[destructiveHint & idempotentHint<br/>become meaningful]
    D --> E[idempotentHint: true<br/>Re-running safe]
    D --> F[idempotentHint: false<br/>May fail on retry]
    D --> G[destructiveHint: true<br/>Cannot undo]

Note: idempotentHint and destructiveHint are meaningful only when readOnlyHint is false, as defined by the MCP specification.

Sources: src/filesystem/README.md:42-44

Security Model

The Filesystem Server implements multiple security layers to prevent unauthorized file system access.

Path Validation

graph TD
    A[Incoming Path] --> B{Normalize Path}
    B --> C{Relative to allowed directory?}
    C -->|No| D[Reject with error]
    C -->|Yes| E{Symlink traversal safe?}
    E -->|No| D
    E -->|Yes| F[Allow operation]

Validation Rules:

1. All paths are normalized before comparison
2. Symbolic links are resolved and checked against allowed directories
3. Attempting to escape allowed directories via .. or symlinks is blocked
4. Operations are rejected if the resolved path falls outside permitted boundaries

Sources: src/filesystem/path-validation.ts:1-30

Allowed Directories Configuration

Docker Example:

docker run -i --rm \
  --mount type=bind,src=/host/path,dst=/projects/path \
  mcp/filesystem /projects

NPX Example:

npx -y @modelcontextprotocol/server-filesystem \
  /Users/username/Desktop \
  /path/to/allowed/dir

Sources: src/filesystem/README.md:55-75

Installation Methods

Docker

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX (Unix/macOS)

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

NPX (Windows)

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Sources: src/filesystem/README.md:55-95

Tool Detailed Reference

read_text_file

Reads complete file contents as UTF-8 text regardless of file extension.

Constraints: Cannot specify both head and tail simultaneously.

Sources: src/filesystem/README.md:98-110

read_media_file

Reads image or audio files and returns base64-encoded data with MIME type.

Returns:

• blob: Base64-encoded file content
• mimeType: Corresponding MIME type (e.g., image/png, audio/mpeg)

Sources: src/filesystem/README.md:112-120

edit_file

Performs selective edits using pattern matching with indentation preservation.

Edit Operation Schema:

{
  oldText: string;  // Text to search for (can be substring)
  newText: string;  // Replacement text
}

Features:

• Line-based and multi-line content matching
• Whitespace normalization with indentation preservation
• Git-style diff output with context
• Preview changes with dry run mode

Best Practice: Always use dryRun: true first to preview changes before applying them.

Sources: src/filesystem/README.md:132-150

move_file

Moves or renames files and directories.

Behavior:

• Fails if destination already exists
• Deletes source file after successful move
• destructiveHint: true - operation cannot be automatically undone

Sources: src/filesystem/README.md:165-175

list_directory_with_sizes

Lists directory contents with detailed file size information.

Returns: Detailed listing including file sizes and summary statistics (total files, directories, combined size).

Sources: src/filesystem/README.md:155-163

Building from Source

Prerequisites

• Node.js 22+
• npm or docker

Docker Build

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Local Development

cd src/filesystem
npm install
npm run build

Sources: src/filesystem/README.md:45-50

MCP Protocol Integration

Resources

The server may expose allowed directories as MCP Resources with the roots:// URI scheme.

sequenceDiagram
    participant Client
    participant Server
    participant FileSystem
    Client->>Server: List Roots
    Server->>Server: Check roots-utils
    Server-->>Client: Allowed directory list
    Client->>Server: Tool call (e.g., read_file)
    Server->>FileSystem: Operation
    FileSystem-->>Server: Result
    Server-->>Client: Tool response

Sources: src/filesystem/roots-utils.ts:1-25

License

The Filesystem Server is licensed under the MIT License. This permits free use, modification, and distribution subject to MIT License terms.

Sources: src/filesystem/README.md:51-54

Related Pages

Related topics: Everything Server

Memory Server

The Memory Server is an MCP (Model Context Protocol) server implementation that provides persistent knowledge graph capabilities for AI assistants like Claude. It enables AI models to maintain long-term memory across conversations by storing and retrieving structured information about users, entities, relationships, and events.

Overview

The Memory Server implements a knowledge graph storage system that allows AI assistants to:

• Store information about users and their characteristics
• Maintain relationships between entities
• Retrieve relevant context from previous interactions
• Update memory dynamically during conversations

Sources: src/memory/package.json:3

graph TD
    A[Claude Conversation] --> B[Memory Server]
    B --> C[Knowledge Graph Storage]
    C --> D[JSONL File Storage]
    
    B --> E[Memory Retrieval]
    E --> F[Return Entities & Relations]
    
    B --> G[Memory Update]
    G --> H[Create/Update Entities]
    G --> I[Create Relations]
    I --> C

Architecture

The Memory Server is built using the Model Context Protocol SDK and stores data in a JSONL (JSON Lines) format file. The server provides tools for managing a graph-based knowledge structure with entities and relations.

Sources: src/memory/package.json:1-2

Core Components

Installation

Docker Installation

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-v",
        "claude-memory:/app/dist",
        "--rm",
        "mcp/memory"
      ]
    }
  }
}

Sources: src/memory/README.md

NPX Installation (Unix/macOS)

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

NPX Installation (Windows)

Windows requires using cmd with /c flag to launch npx:

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

Configuration

Environment Variables

Custom Storage Path Example

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

Sources: src/memory/README.md

Memory Operations

The Memory Server supports the following core operations:

User Identification

The system assumes interaction with a default user and proactively identifies them if not already known:

- Assume interaction with default_user
- Proactively identify user if not already done

Memory Retrieval

At the start of each conversation, the system retrieves relevant information from the knowledge graph:

- Begin chat by saying "Remembering..."
- Retrieve all relevant information from knowledge graph
- Reference knowledge graph as "memory"

Memory Categories

During conversation, the system stores new information in these categories:

Sources: src/memory/README.md

Memory Update Process

When new information is gathered during interaction:

graph TD
    A[New Information Gathered] --> B{Is it recurring?}
    B -->|Organization| C[Create Entity for Organization]
    B -->|Person| D[Create Entity for Person]
    B -->|Event| E[Create Entity for Event]
    C --> F[Connect to Current Entities]
    D --> F
    E --> F
    F --> G[Create Relations]
    G --> H[Update Knowledge Graph]

The update process:

1. Creates entities for recurring organizations, people, and significant events
2. Connects new entities to existing entities using relations
3. Returns requested entities and their relations
4. Silently skips non-existent nodes

Usage with Claude Desktop

Setup Configuration

Add the following to your claude_desktop_config.json:

#### Docker Configuration

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    }
  }
}

#### NPX Configuration

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

System Prompt Configuration

For optimal memory utilization, configure a custom prompt in the "Custom Instructions" field of your Claude.ai Project:

Follow these steps for each interaction:

1. User Identification:
   - Assume interaction with default_user
   - Proactively identify if not already known

2. Memory Retrieval:
   - Begin chat by saying "Remembering..."
   - Retrieve all relevant information from knowledge graph
   - Reference knowledge graph as "memory"

3. Memory Categories:
   While conversing, be attentive to:
   a) Basic Identity (age, gender, location, job title, etc.)
   b) Behaviors (interests, habits, etc.)
   c) Preferences (communication style, preferred language)
   d) Goals (goals, targets, aspirations)
   e) Relationships (personal/professional up to 3 degrees)

4. Memory Update:
   If new information gathered:
   a) Create entities for recurring organizations, people, events
   b) Connect them to current entities using relations

Sources: src/memory/README.md

Technical Specifications

Package Information

Sources: src/memory/package.json:1-11

Build Configuration

{
  "scripts": {
    "build": "tsc && shx chmod +x dist/*.js",
    "prepare": "npm run build",
    "watch": "tsc --watch",
    "test": "vitest run --coverage"
  }
}

Sources: src/memory/package.json:18-22

VS Code Installation

Quick installation is available through one-click buttons in the VS Code marketplace:

• NPX Installation: For npm-based installations
• VS Code Insiders: Separate button for Insiders version

These buttons provide streamlined configuration without manual JSON editing.

Sources: src/memory/README.md

Data Model

Entity Structure

Entities in the knowledge graph include:

• Organizations: Recurring companies, teams, institutions
• People: Users, contacts, individuals mentioned
• Events: Significant occurrences, meetings, milestones

Relation Types

Relations connect entities with semantic meaning:

• Personal relationships (family, friends, colleagues)
• Professional relationships (team members, stakeholders)
• Temporal relationships (event connections)
• Hierarchical relationships (org charts, reporting structures)

Return Values

Development

Running from Source

1. Clone the repository
2. Navigate to src/memory
3. Install dependencies
4. Build using npm run build

Testing

cd src/memory
npm test

Summary

The Memory Server provides a flexible, knowledge-graph-based memory system for AI assistants. It enables persistent storage of user information, entity relationships, and conversation context across multiple sessions. By integrating with the Model Context Protocol, it offers standardized MCP tool interfaces for memory operations while maintaining data in a portable JSONL format.

Key benefits include:

• Persistent Memory: Information persists across sessions
• Graph-based Relationships: Rich entity connections
• Flexible Storage: JSONL format allows easy backup and inspection
• MCP Standard: Compatible with any MCP-compliant client

Related Pages

Related topics: Filesystem Server

Git Server

Documentation Status: The Git Server (src/git/) source files were not included in the current repository context. This page provides general information based on MCP server patterns observed in this repository. For accurate implementation details, refer to the actual source files listed above.

Overview

The Git Server is a Model Context Protocol (MCP) server implementation that provides Git repository interaction capabilities to AI assistants and other MCP clients. Based on the project's architecture patterns, this server follows the same conventions as other MCP servers in the modelcontextprotocol/servers repository.

The server enables AI models to perform Git operations such as viewing history, examining commits, browsing branches, and analyzing repository state through standardized MCP tool interfaces.

Architecture

Based on the patterns observed in other servers within this repository, the Git Server follows a modular architecture:

graph TD
    A[MCP Client] -->|JSON-RPC| B[Git Server Entry Point]
    B --> C[Tool Handlers]
    C --> D[Git Operations Layer]
    D --> E[Local Git Repository]
    B --> F[Resource Providers]
    F --> G[Repository Resources]

Server Structure

Directory Layout

Following the repository conventions (per CLAUDE.md):

src/git/
├── pyproject.toml           # Python package configuration
├── src/
│   └── mcp_server_git/
│       ├── __init__.py
│       └── server.py        # Main server implementation
├── README.md                # Server-specific documentation
└── tests/                   # Test suite

Package Configuration

The server uses hatchling as its build system, consistent with other Python servers in this repository. Package configuration is defined in pyproject.toml.

Based on patterns from other servers:

• Package manager: uv (not pip) - Sources: CLAUDE.md
• Python version: >= 3.10 (per-server .python-version file) - Sources: CLAUDE.md
• Type checking: pyright - Sources: CLAUDE.md
• Linting: ruff - Sources: CLAUDE.md

Installation Methods

Based on the standard MCP server installation patterns in this repository:

Using uvx (Recommended)

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

Using pip

{
  "mcpServers": {
    "git": {
      "command": "python",
      "args": ["-m", "mcp_server_git"]
    }
  }
}

Using Docker

{
  "mcpServers": {
    "git": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/git"]
    }
  }
}

Configuration

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

On Windows, wrap with cmd /c:

{
  "mcpServers": {
    "git": {
      "command": "cmd",
      "args": ["/c", "uvx", "mcp-server-git"]
    }
  }
}

Development

Building

Docker build:

docker build -t mcp/git -f src/git/Dockerfile .

Testing

cd src/git && uv sync --frozen --all-extras --dev
uv run pytest

Type Checking

uv run pyright

Linting

uv run ruff check .

Tool Interface

Based on MCP server conventions, the Git Server exposes tools via the MCP protocol. Common Git operations likely include:

Comparison with Other MCP Servers

The Git Server follows the same architectural patterns as other servers in this repository:

Contributing

Contributions to the Git Server follow the general guidelines defined in the repository's CLAUDE.md:

• Accepted: Bug fixes, usability improvements, enhancements demonstrating MCP protocol features
• Code Style: Python typing with type hints enforced via pyright
• Testing: pytest with proper async patterns
• Linting: ruff for code style enforcement

For contribution guidelines, see: https://github.com/modelcontextprotocol/servers

License

This MCP server is licensed under the MIT License, consistent with other servers in the repository. Users are free to use, modify, and distribute the software subject to MIT License terms.

Related Pages

Related topics: Fetch Server

Time Server

The Time Server is a Python-based MCP (Model Context Protocol) server that provides timezone-aware time retrieval and conversion capabilities. It enables AI assistants and MCP clients to query current time in any timezone and perform time conversions between different time zones.

Overview

The Time Server exposes two primary tools that allow clients to:

• Retrieve the current time for a specified timezone
• Convert times between different timezones

The server automatically detects the system's timezone by default but allows customization through command-line arguments. It follows the MCP specification for tool definitions and responses.

Architecture

graph TD
    A[MCP Client] -->|Tool Request| B[Time Server]
    B -->|Execute| C[get_current_time Tool]
    B -->|Execute| D[convert_time Tool]
    C -->|Query| E[System Timezone]
    C -->|Query| F[Specified Timezone]
    D -->|Calculate| G[Timezone Conversion]
    G --> H[Time Difference]
    B -->|JSON Response| A

Tools

get_current_time

Retrieves the current time for a specified timezone.

Parameters:

Example Request:

{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Europe/Warsaw"
  }
}

Response:

{
  "timezone": "Europe/Warsaw",
  "datetime": "2024-01-01T13:00:00+01:00",
  "is_dst": false
}

convert_time

Converts a time from one timezone to another.

Parameters:

Example Request:

{
  "name": "convert_time",
  "arguments": {
    "source_timezone": "America/New_York",
    "time": "16:30",
    "target_timezone": "Asia/Tokyo"
  }
}

Response:

{
  "source": {
    "timezone": "America/New_York",
    "datetime": "2024-01-01T12:30:00-05:00",
    "is_dst": false
  },
  "target": {
    "timezone": "Asia/Tokyo",
    "datetime": "2024-01-01T12:30:00+09:00",
    "is_dst": false
  },
  "time_difference": "+13.0h"
}

Installation

The Time Server supports multiple installation methods.

Using uvx (Recommended)

uvx mcp-server-time

Using pip

pip install mcp-server-time
python -m mcp_server_time

Using Docker

cd src/time
docker build -t mcp/time .
docker run -i --rm mcp/time

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

Using pip:

{
  "mcpServers": {
    "time": {
      "command": "python",
      "args": ["-m", "mcp_server_time"]
    }
  }
}

VS Code

Use the one-click installation buttons available in the README, or configure manually:

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

Zed Editor

{
  "context_servers": {
    "mcp-server-time": {
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}

Docker Configuration

{
  "mcpServers": {
    "time": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "LOCAL_TIMEZONE", "mcp/time"]
    }
  }
}

Customization

System Timezone Override

By default, the server automatically detects your system's timezone. Override this using the --local-timezone argument:

{
  "command": "python",
  "args": ["-m", "mcp_server_time", "--local-timezone=America/New_York"]
}

Environment Variable (Docker)

Pass the timezone via the LOCAL_TIMEZONE environment variable when using Docker:

docker run -i --rm -e LOCAL_TIMEZONE=Europe/London mcp/time

Debugging

Use the MCP Inspector for debugging:

For uvx installations:

npx @modelcontextprotocol/inspector uvx mcp-server-time

For local development:

cd path/to/servers/src/time
npx @modelcontextprotocol/inspector uv run mcp-server-time

Example Interactions

Query Current Time

Time Conversion

Data Model

Time Response Schema

Conversion Response Schema

License

The Time Server is licensed under the MIT License, allowing free use, modification, and distribution subject to the terms and conditions specified in the LICENSE file.

See Also

• Memory Server - Persistent memory storage
• Fetch Server - HTTP fetch capabilities
• Filesystem Server - File operations
• MCP Specification - Protocol documentation

Related Pages

Related topics: Time Server

Fetch Server

The Fetch Server is a Model Context Protocol (MCP) server that provides web content fetching capabilities. It enables Large Language Models (LLMs) to retrieve and process content from web pages, converting HTML to markdown for easier consumption.

Overview

The Fetch Server acts as an intermediary between LLMs and web content, handling the complexities of HTTP requests, HTML parsing, and markdown conversion. This abstraction allows models to access web information without needing direct HTTP implementation capabilities.

graph TD
    A["LLM / MCP Client"] --> B["Fetch Server"]
    B --> C["HTTP Request"]
    C --> D["Web Server"]
    D --> E["HTML Response"]
    E --> B
    B --> F["Markdown Conversion"]
    F --> A

Key Capabilities

[!CAUTION]

This server can access local/internal IP addresses and may represent a security risk. Exercise caution when using this MCP server to ensure it does not expose any sensitive data.

Tools

fetch

The primary tool provided by the Fetch Server for retrieving web content.

{
  name: "fetch",
  description: "Fetches a URL from the internet and extracts its contents as markdown.",
  inputSchema: {
    url: string,           // required
    max_length?: number,   // optional, default: 5000
    start_index?: number, // optional, default: 0
    raw?: boolean          // optional, default: false
  }
}

#### Parameters

Sources: src/fetch/README.md

#### Usage Example

{
  "name": "fetch",
  "arguments": {
    "url": "https://example.com/article",
    "max_length": 10000,
    "start_index": 0
  }
}

#### Response Format

{
  "content": [
    {
      "type": "text",
      "text": "# Article Title\n\nConverted markdown content..."
    }
  ]
}

Chunked Reading

The fetch tool truncates responses by default. By using the start_index argument, you can specify where to start the content extraction, enabling models to read a webpage in chunks until they find the information they need.

graph LR
    A["Initial Request<br/>start_index=0"] --> B["First Chunk"]
    B --> C{"Need More?"}
    C -->|Yes| D["Request with<br/>start_index=N"]
    D --> B
    C -->|No| E["Complete"]

Installation

The Fetch Server supports multiple installation methods. Choose the one that best fits your environment.

Using uv (Recommended)

When using uv, no specific installation is needed. Use uvx to directly run the server:

uvx mcp-server-fetch

Sources: src/fetch/README.md

Using pip

Alternatively, install via pip:

pip install mcp-server-fetch

After installation, run as a script:

python -m mcp_server_fetch

Using Docker

docker run -i --rm mcp/fetch

Optional Dependency

Optionally, install Node.js for a more robust HTML simplifier:

# This will cause the fetch server to use a different HTML simplifier
# that is more robust for complex web pages

Configuration

Claude.app Configuration

Add the following to your Claude settings:

#### Using uvx

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

#### Using Docker

{
  "mcpServers": {
    "fetch": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/fetch"]
    }
  }
}

#### Using pip

{
  "mcpServers": {
    "fetch": {
      "command": "python",
      "args": ["-m", "mcp_server_fetch"]
    }
  }
}

Sources: src/fetch/README.md

VS Code Configuration

For quick installation, use the one-click install buttons available in the README:

• Install with UV in VS Code - Uses uvx mcp-server-fetch
• Install with UV in VS Code Insiders - Uses uvx mcp-server-fetch (insiders version)
• Install with Docker in VS Code - Uses docker command

Customization Options

robots.txt

By default, the server obeys a website's robots.txt file if the request came from the model (via a tool), but not if the request was user-initiated (via a prompt). This can be disabled:

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

User-Agent

The server uses different user-agents based on request origin:

Customize the user-agent:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch", "--user-agent=YourUserAgent"]
    }
  }
}

Proxy Support

Configure the server to use a proxy:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch", "--proxy-url=http://proxy.example.com:8080"]
    }
  }
}

Sources: src/fetch/README.md

Windows Configuration

If experiencing timeout issues on Windows, set the PYTHONIOENCODING environment variable to ensure proper character encoding:

Windows with uvx

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Windows with pip

{
  "mcpServers": {
    "fetch": {
      "command": "python",
      "args": ["-m", "mcp_server_fetch"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Debugging

Use the MCP inspector to debug the server:

For uvx installations

npx @modelcontextprotocol/inspector uvx mcp-server-fetch

For development

cd path/to/servers/src/fetch
npx @modelcontextprotocol/inspector uv run mcp-server-fetch

Prompts

The Fetch Server includes a prompt template:

fetch

• Purpose: Fetch a URL and extract its contents as markdown
• Arguments:
• url (string, required): URL to fetch

Architecture

graph TD
    subgraph "Client Layer"
        A["MCP Client<br/>(Claude, VS Code, etc.)"]
    end
    
    subgraph "Fetch Server"
        B["Request Handler"]
        C["robots.txt Validator"]
        D["User-Agent Manager"]
        E["HTTP Client"]
        F["HTML Parser"]
        G["Markdown Converter"]
    end
    
    subgraph "External"
        H["Target Web Server"]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> H
    H --> E
    E --> F
    F --> G
    G --> A

License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.

Contributing

Contributions are welcome to help expand and improve mcp-server-fetch. Whether you want to add new tools, enhance existing functionality, or improve documentation, your input is valuable.

For examples of other MCP servers and implementation patterns, see the main MCP servers repository.

Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements.

Related Pages

Related topics: Everything Server

Sequential Thinking Server

The Sequential Thinking Server is an MCP (Model Context Protocol) server implementation that provides a structured, step-by-step thinking tool for dynamic and reflective problem-solving. It enables AI assistants to break down complex problems into manageable steps, revise thinking as understanding deepens, and branch into alternative reasoning paths.

Overview

The server exposes a single powerful tool called sequential_thinking that facilitates detailed, iterative reasoning processes. Unlike one-shot responses, this tool allows models to maintain context over multiple thought steps, adjust their approach dynamically, and explore branching reasoning paths when needed.

Key Characteristics:

Sources: package.json:1-6

Features

The Sequential Thinking Server provides the following capabilities:

• Step-by-Step Decomposition — Break complex problems into manageable thought steps
• Iterative Refinement — Revise and refine thoughts as understanding deepens
• Branching Reasoning — Fork into alternative paths of reasoning from any thought
• Dynamic Adjustment — Adjust the total number of thoughts needed on the fly
• Hypothesis Verification — Generate and verify solution hypotheses through structured thinking
• Thought Logging — Optional logging of thought information for debugging and audit

Sources: README.md:1-20

Tool Specification

sequential_thinking

The primary tool provided by this server for structured problem-solving.

Input Schema:

Sources: README.md:35-53

Tool Annotations:

Architecture

graph TD
    A[MCP Host Application] -->|stdio / HTTP| B[Sequential Thinking Server]
    B --> C[sequential_thinking Tool]
    C --> D[Thought State Management]
    D --> E[Optional Logging]
    
    F[Thought Input] -->|thought| C
    F -->|nextThoughtNeeded| C
    F -->|thoughtNumber| C
    F -->|totalThoughts| C
    
    C -->|revision| G[Revises Previous Thought]
    C -->|branch| H[Alternative Branch Created]
    C -->|continuation| I[Next Thought Prompt]

Component Overview

┌─────────────────────────────────────────────────────────────┐
│                    MCP Host (Claude Desktop, VS Code)       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│               Sequential Thinking Server                     │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Tool Handler: sequential_thinking                   │    │
│  │  - Validates input schema                            │    │
│  │  - Processes thought parameters                      │    │
│  │  - Manages thought state                             │    │
│  └─────────────────────────────────────────────────────┘    │
│                              │                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Logging Module (optional)                           │    │
│  │  - Controlled by DISABLE_THOUGHT_LOGGING env var     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Installation

Package Requirements

The server requires Node.js and is distributed as an npm package. It can also be run via Docker.

Sources: package.json:18-22

npx (Unix/Linux/macOS)

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

npx (Windows)

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Docker

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mcp/sequentialthinking"]
    }
  }
}

Sources: README.md:1-50

Configuration

Claude Desktop Configuration

Add the following to claude_desktop_config.json:

#### NPX Installation

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

#### Docker Installation

{
  "mcpServers": {
    "sequentialthinking": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mcp/sequentialthinking"]
    }
  }
}

VS Code Configuration

Use the quick installation buttons in the README, or manually configure with:

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

Sources: README.md:90-130

Environment Variables

When DISABLE_THOUGHT_LOGGING is set to true, the server will not log any thought-related information, providing a more private reasoning process.

Sources: README.md:70-72

Building from Source

Prerequisites

• Node.js
• npm
• TypeScript

Build Commands

# Clone the repository
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/sequentialthinking

# Install dependencies
npm install

# Build the TypeScript project
npm run build

The build process:

1. Compiles TypeScript using tsc
2. Sets executable permissions on compiled JavaScript files using shx chmod +x

Sources: package.json:12-16

Docker Build

docker build -t mcp/sequentialthinking -f src/sequentialthinking/Dockerfile .

Usage Patterns

When to Use Sequential Thinking

The sequential_thinking tool is designed for:

Sources: README.md:55-68

Verification Workflow

graph LR
    A[Install Server] --> B[Restart MCP Host]
    B --> C[Verify Tool Appears]
    C --> D[Ask Complex Question]
    D --> E[Model Invokes Tool Multiple Times]
    E --> F[Observe Step-by-Step Reasoning]

Manual Verification Steps:

1. Install the server in your MCP host
2. Restart or reload the host so it reconnects to the server
3. Confirm the sequential_thinking tool appears in the host's MCP tool list
4. Ask the host to solve a non-trivial problem step-by-step
5. Verify the host invokes the tool multiple times instead of returning a one-shot answer

Sources: README.md:145-165

Reasoning Branching Example

graph TD
    A[Thought 1: Initial Problem] --> B[Thought 2: Approach A]
    B --> C[Thought 3: Explore Branch A1]
    C --> D{Decision Point}
    D -->|Revert| E[Thought 4: Revises Thought 2<br/>branchId: branch-A]
    D -->|Continue| F[Thought 5: Continue on A1]
    E --> G[Thought 5: Alternative Path]

The tool supports:

• Revisions — Mark thoughts with isRevision: true and revisesThought to indicate corrections
• Branches — Use branchFromThought and branchId to create alternative reasoning paths
• Dynamic Length — Adjust totalThoughts as the reasoning progresses

Dependencies

Dev Dependencies:

Sources: package.json:18-40

Testing

The project includes Vitest tests with coverage reporting:

npm test

This runs tests with coverage using vitest run --coverage.

Sources: package.json:15

License

This MCP server is licensed under the MIT License. Users are free to use, modify, and distribute the software subject to the terms and conditions of the MIT License.

Sources: README.md:80-83

See Also

• Model Context Protocol Specification
• MCP Servers Repository
• Bug Tracker

Doramagic Pitfall Log

Doramagic extracted 6 source-linked risk signals. Review them before installing or handing real data to the project.

1. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | README/documentation is current enough for a first validation pass.

2. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | last_activity_observed missing

3. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | no_demo; severity=medium

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | no_demo; severity=medium

5. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | issue_or_pr_quality=unknown

6. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using servers with real data or production workflows.

• The filesystem server stopped working with the OpenAI Agent SDK. - github / github_issue
• Filesystem extension: Frequent timeout or outright failures since claude - github / github_issue
• filesystem MCP server doesn't support legal Windows pathnames in claude_ - github / github_issue
• Latest release of @modelcontextprotocol/server-filesystem is not on npmj - github / github_issue
• Filesystem server canonicalizes configured Windows mapped-drive paths to - github / github_issue
• Add baselings-mcp — 42 DeFi tools for Base chain (swaps, reactor burns, - github / github_issue
• confusing documentation - github / github_issue
• memory: safer persistence defaults, atomic writes, quotas, redaction, an - github / github_issue
• puppeteer: update old MCP SDK and add browser-automation guardrails by d - github / github_issue
• Reference implementation: self-evolving macOS MCP server (Swift, 71 tool - github / github_issue
• Schema quality: missing property descriptions across official MCP server - github / github_issue
• A curated list of Model Context Protocol (MCP) servers : r/ClaudeAI - reddit / searxng_indexed