Welcome! This repository is a collection of guides, utilities, and server implementations for the Model Context Protocol (MCP) created while learning MCP. It reflects ongoing exploration and development with this exciting new standard for creating powerful Agent capabilities. Questions and feedback are welcome! 🚀
Disclaimer: The resources in this repository (guides, utilities, server implementations, and the MCP TypeScript Template) were developed independently by cyanheads while exploring the Model Context Protocol. This project is not officially affiliated with the Model Context Protocol organization. Links to official MCP resources are provided below. I appreciate the work of the official MCP team on the specification, SDKs, and documentation!
Introduction | Official Resources | Guides | Utilities | Servers | Getting Started | License
MCP Template Repo: mcp-ts-template
Guides: MCP Client Development | MCP Server Development | cyanheads-custom-llms.txt
Utilities: mcp-reporter
Servers: atlas-mcp-server | filesystem-mcp-server | git-mcp-server | github-mcp-server | mcp-reporter | mcp-ts-template | mentor-mcp-server | ntfy-mcp-server | obsidian-mcp-server | perplexity-mcp-server | toolkit-mcp-server
Key links to official Model Context Protocol documentation, specifications, and community resources (modelcontextprotocol.io):
| Page / Section | Link Path |
|---|---|
| Introduction | /introduction |
| Server Quickstart | /quickstart/server |
| Specification Home | /specification |
| ↳ Architecture | /specification/architecture |
| ↳ Base Protocol | /specification/basic |
| ↳ Server Features | /specification/server |
| ↳ Client Features | /specification/client |
| ↳ Auth Spec (2025-03-26) | /.../authorization |
| Schema Definition (TS) | spec/.../schema.ts |
| Contributing Guide | CONTRIBUTING.md |
| GitHub Organization | github.com/... |
| Specification Discussions | spec/discussions |
| Organization Discussions | orgs/discussions |
| JSON-RPC 2.0 Spec | jsonrpc.org |
SDKs & Tools:
| Language | SDK Repository |
|---|---|
| TypeScript | typescript-sdk |
| Python | python-sdk |
| Kotlin | kotlin-sdk |
| Java | java-sdk |
| C# | csharp-sdk |
| Tool | Repository |
| MCP Inspector (Debugging tool) | inspector |
The Model Context Protocol (MCP) is an open standard designed to standardize how AI applications (clients/hosts) connect to and interact with external data sources and tools (servers). Think of it like USB-C for AI: a universal way to plug capabilities into LLM applications.
Key Benefits:
- Consistent Interface: Standardized methods for LLMs to access tools and resources.
- Enhanced Capabilities: Empowers LLMs to interact with databases, APIs, local systems, and more.
- Security & Control: Provides structured access patterns with built-in validation and clear boundaries.
- Extensibility: Easily add new capabilities via servers without modifying core LLM applications.
- Modularity: Develop and maintain specialized functionalities in isolated, reusable server components.
For a more in-depth introduction to MCP, including its design philosophy and technical details, visit the official site: modelcontextprotocol.io.
| Project | Description |
|---|---|
| mcp-ts-template | A beginner-friendly, production-ready TypeScript template for building MCP servers and clients. Includes essential utilities, examples, and type safety for a solid starting point. |
| Guide | Description |
|---|---|
| MCP Client Development Guide | Learn how to build applications that consume MCP server capabilities. Covers core architecture, lifecycle, tools/resources, security, examples, and advanced topics. (Note: Needs update for latest spec changes) |
| MCP Server Development Guide | Comprehensive guide to building MCP servers. Covers core architecture, protocol fundamentals, server lifecycle, transports (Stdio, Streamable HTTP), building with the TypeScript SDK, defining Tools/Resources/Prompts, advanced features (sampling, roots, streaming, progress, subscriptions, completions), security best practices (updated for Auth Spec 2025-03-26), troubleshooting, and example implementations. (Updated May 2025) |
| Cyanhead's MCP 'llms.txt' | A custom llms.txt for faster TypeScript MCP server development using the high-level SDK (McpServer). Tailored for LLM consumption, it covers key concepts, high-level examples, security, and dynamic capabilities, updated for Spec 2025-03-26 & TS SDK v1.11.0. |
| Project | Description |
|---|---|
| mcp-reporter | A streamlined utility that generates comprehensive capability reports for MCP servers. Helps developers understand available functionality across their MCP ecosystem for documentation and integration. |
This repository hosts several example MCP server implementations, showcasing different capabilities:
| Project | Description |
|---|---|
| atlas-mcp-server | ATLAS (Adaptive Task & Logic Automation System), a Neo4j-powered task management system designed for LLM Agents. It uses a three-tier architecture (Projects, Tasks, Knowledge) to manage complex workflows and includes Deep Research scaffolding. |
| filesystem-mcp-server | Offers platform-agnostic file system capabilities for AI agents via MCP. Enables reading, writing, updating, and managing files/directories, featuring advanced search/replace and directory traversal. |
| git-mcp-server | Provides an enterprise-ready MCP interface for Git operations. Allows LLM agents to initialize, clone, branch, commit, and manage repositories via STDIO & Streamable HTTP. |
| github-mcp-server | Integrates with the GitHub API via MCP, built in TypeScript. Provides a structured interface for LLM agents to manage repositories, issues, pull requests, code, files, and releases. |
| mentor-mcp-server | Offers AI-powered mentorship via MCP using Deepseek-Reasoning R1 through the Deepseek API. Provides LLM agents with a 'second opinion' for code review, design critique, writing feedback, and brainstorming. |
| ntfy-mcp-server | Integrates with the ntfy.sh push notification service via MCP. Enables LLM agents to send highly customizable notifications to external devices. |
| obsidian-mcp-server | Enables LLMs to interact securely with Obsidian vaults via MCP. Offers token-aware tools for searching, navigating, and updating Obsidian notes, facilitating seamless knowledge base management with Properties management. |
| perplexity-mcp-server | Unlocks Perplexity's search-augmented AI capabilities for LLM agents via MCP. Provides access to real-time web information with robust error handling, secure validation, and optional reasoning transparency (showThinking). |
| toolkit-mcp-server | Provides essential system utilities and tools for LLM agents via MCP, including IP geolocation, network diagnostics, system monitoring, cryptographic operations, and QR code generation. |
- Explore the Guides: Understand MCP concepts and development approaches using the Client and Server guides.
- Select a Server: Choose one relevant to your needs from the MCP Servers section and follow its specific setup instructions in its repository.
- Connect a Client: Use an existing MCP-compatible client (like Claude Desktop, Cline, etc.) or build your own using the Client Development Guide.
- Experiment & Contribute: Try out the tools and consider contributing via issues or pull requests on the respective project repositories.
This project and its components are licensed under the Apache License 2.0. See the LICENSE file for details, and check individual component repositories for any specific licensing nuances.