mcp-server
🌟 Model Context Protocol (MCP)
📋 Table of Contents
- 🌟 Model Context Protocol (MCP) - Complete Information Guide
- 📋 Table of Contents
- 🎯 What is MCP?
- 🏗️ Architecture Overview
- 🔧 Core Features
- 📚 Official SDKs
- 🖥️ MCP Clients
- 🔌 Reference Servers
- 🏢 Official Integrations
- 🌍 Community Servers
- 🛠️ Frameworks & Tools
- 📖 Resources & Learning
- 🔒 Security & Trust
- 🚀 Getting Started
🎯 What is MCP?
The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
🌟 Key Benefits
- 🔗 Standardized Integration: One protocol to connect any LLM application with any data source
- 🧩 Composable Architecture: Mix and match servers to build powerful AI workflows
- 🔒 Security First: Built-in security principles and user consent controls
- 🚀 Easy to Build: Simple interfaces for creating servers and clients
- 🌐 Growing Ecosystem: 500+ servers and 50+ clients already available
🎨 Core Concepts
MCP provides three main primitives:
- 📄 Resources: Context and data for the user or AI model to use
- 🎯 Prompts: Templated messages and workflows for users
- 🛠️ Tools: Functions for the AI model to execute
- 🔄 Sampling: Server-initiated agentic behaviors and recursive LLM interactions
🏗️ Architecture Overview
MCP follows a client-host-server architecture where each host can run multiple client instances:```mermaid
graph TB
Host[🏠 Host Application]
Client1[📱 MCP Client 1]
Client2[📱 MCP Client 2]
Client3[📱 MCP Client 3]
Server1[🔧 Database Server]
Server2[🌐 Web API Server]
Server3[📁 File System Server]
Server4[🔍 Search Server]
Host --> Client1
Host --> Client2
Host --> Client3
Client1 --> Server1
Client2 --> Server2
Client3 --> Server3
Client3 --> Server4
style Host fill:#e1f5fe
style Client1 fill:#f3e5f5
style Client2 fill:#f3e5f5
style Client3 fill:#f3e5f5
style Server1 fill:#e8f5e8
style Server2 fill:#e8f5e8
style Server3 fill:#e8f5e8
style Server4 fill:#e8f5e8
### 🔧 Components
- **🏠 Host**: The container and coordinator (creates clients, manages security, handles authorization)
- **📱 Clients**: Isolated server connections (protocol negotiation, message routing, security boundaries)
- **🔧 Servers**: Specialized context and capabilities providers (expose resources, tools, prompts)
---
## 🔧 Core Features
### 📄 Resources
Resources allow servers to share data that provides context to language models:
- 📁 Files and documents
- 🗄️ Database schemas
- 🌐 API responses
- 📊 Application-specific information
### 🎯 Prompts
Pre-defined templates or instructions that guide language model interactions:
- 🔄 Reusable templates
- 📝 Dynamic arguments
- 🎨 Multi-step workflows
- 💡 Interactive guidance
### 🛠️ Tools
Executable functions that allow models to perform actions:
- 🔍 Query databases
- 📞 Call APIs
- 🧮 Perform computations
- 🔄 Execute workflows
### 🔄 Sampling
Server-initiated LLM interactions for agentic behaviors:
- 🤖 Nested LLM calls
- 🔄 Recursive interactions
- 🎯 Context-aware completions
- 👤 Human-in-the-loop controls
---
## 📚 Official SDKs
| Language | Repository | Stars | Description |
|----------|------------|-------|-------------|
| **TypeScript** | typescript-sdk | | Official TypeScript SDK |
| **Python** | python-sdk | | Official Python SDK |
| **Java** | java-sdk | | Official Java SDK (with Spring AI) |
| **Kotlin** | kotlin-sdk | | Official Kotlin SDK (with JetBrains) |
| **C#** | csharp-sdk | | Official C# SDK (with Microsoft) |
| **Swift** | swift-sdk | | Official Swift SDK |
| **Ruby** | ruby-sdk | | Official Ruby SDK (with Shopify) |
### 🚀 Quick Start Examples
🟦 TypeScript Example```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// Create an MCP server
const server = new McpServer({
name: "Demo",
version: "1.0.0"
});
// Add a tool
server.tool("add",
{ a: z.number(), b: z.number() },
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }]
})
);
// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
🐍 Python Example```python
from mcp.server import Server
import mcp.types as types
app = Server("demo-server")
@app.tool()
async def add(a: float, b: float) -> str:
"""Add two numbers together."""
return str(a + b)
Run with: python -m mcp.server.stdio server.py
---
## 🖥️ MCP Clients
### 🌟 Featured Clients
| Client | Features | Resources | Prompts | Tools | Sampling | Notes |
|--------|----------|-----------|---------|-------|----------|-------|
| **🤖 Claude Desktop** | ✅ Full Support | ✅ | ✅ | ✅ | ❌ | Official Anthropic client |
| **🌐 Claude.ai** | ✅ Remote MCP | ✅ | ✅ | ✅ | ❌ | Web-based client |
| **💻 Cursor** | ✅ Tools | ❌ | ❌ | ✅ | ❌ | AI code editor |
| **🌪️ Windsurf** | ✅ Tools + Discovery | ❌ | ❌ | ✅ | ✅ | Agentic IDE |
| **🔧 Cline** | ✅ Tools + Resources | ✅ | ❌ | ✅ | ✅ | VS Code extension |
| **🔄 Continue** | ✅ Full Support | ✅ | ✅ | ✅ | ❓ | Open-source AI assistant |
### 📱 Complete Client List
🖥️ Desktop Applications
- **🤖 Claude Desktop App** - Full MCP support with local and remote servers
- **💻 Cursor** - AI code editor with tool support
- **🌪️ Windsurf Editor** - Agentic IDE with AI Flow
- **🔧 Cline** - Autonomous coding agent for VS Code
- **🔄 Continue** - Open-source AI code assistant
- **⚡ BoltAI** - Native AI chat client with MCP support
- **📝 Tome** - Cross-platform desktop app for local LLMs
- **🎨 Witsy** - AI desktop assistant for macOS, Windows, Linux
🌐 Web Applications
- **🌐 Claude.ai** - Web-based Claude with remote MCP servers
- **🎯 AgenticFlow** - No-code AI platform with 10,000+ tools
- **🔍 Glama** - AI workspace with MCP integration
- **🧠 MindPal** - No-code platform for AI agents
- **🎪 Superinterface** - AI infrastructure platform
- **📊 Lutra** - AI agent for automated workflows
🛠️ Developer Tools
- **📊 Postman** - API client with MCP testing support
- **🔍 VS Code GitHub Copilot** - GitHub Copilot with MCP integration
- **🚀 GenAIScript** - JavaScript toolbox for LLM prompts
- **🎯 TheiaAI/TheiaIDE** - AI-enhanced development environment
- **🔧 JetBrains** - Work with code using JetBrains IDEs
📱 Mobile & Messaging
- **📱 WhatsMPC** - MCP client for WhatsApp
- **💬 Slack MCP Client** - Bridge between Slack and MCP servers
- **🎮 TypingMind App** - Advanced frontend for LLMs
---
## 🔌 Reference Servers
These servers demonstrate MCP features and the official SDKs:
| Server | Description | Language | Features | Repository |
|--------|-------------|----------|----------|------------|
| **🔍 Brave Search** | Web and local search using Brave's API | TypeScript | Search, Web Content | GitHub |
| **📁 Filesystem** | Secure file operations with access controls | TypeScript | File Management | GitHub |
| **🔧 Git** | Tools to read, search, and manipulate Git repositories | Python | Version Control | GitHub |
| **🐙 GitHub** | Repository management and GitHub API integration | TypeScript | Code Management | GitHub |
| **🗄️ PostgreSQL** | Read-only database access with schema inspection | Python | Database | GitHub |
| **🕷️ Puppeteer** | Browser automation and web scraping | TypeScript | Web Automation | GitHub |
| **💾 Memory** | Knowledge graph-based persistent memory system | TypeScript | Data Storage | GitHub |
| **⏰ Time** | Time and timezone conversion capabilities | TypeScript | Utilities | GitHub |
---
## 🏢 Official Integrations
Production-ready MCP servers maintained by companies:
### 🌟 Enterprise Platforms
☁️ Cloud & Infrastructure
- **☁️ AWS** - Specialized MCP servers for AWS services | GitHub
- **🔵 Microsoft Azure** - Azure services integration | GitHub
- **🌐 Cloudflare** - Deploy and configure Cloudflare resources | GitHub
- **🔧 Pulumi** - Infrastructure as Code management | GitHub
- **⚙️ Terraform** - Infrastructure automation | GitHub
- **🐳 Kubernetes** - Container orchestration management | GitHub
🗄️ Databases & Analytics
- **🐘 PostgreSQL** - Database operations and queries | GitHub
- **🏠 ClickHouse** - Real-time analytics database | GitHub
- **🔍 Elasticsearch** - Search and analytics engine | GitHub
- **📊 BigQuery** - Google's data warehouse | GitHub
- **🦆 MotherDuck** - DuckDB cloud analytics | GitHub
- **⚡ SingleStore** - Real-time database platform | GitHub
- **🌟 StarRocks** - High-performance analytics database | GitHub
🛠️ Development Tools
- **🐙 GitHub** - Official GitHub MCP server | GitHub
- **🦊 GitLab** - GitLab API integration | GitHub
- **🔄 CircleCI** - CI/CD pipeline management | GitHub
- **🚀 Buildkite** - Build automation platform | GitHub
- **🧪 Sentry** - Error tracking and monitoring | GitHub
- **📊 Grafana** - Monitoring and observability | GitHub
💼 Business Applications
- **📧 Slack** - Team communication platform | GitHub
- **📝 Notion** - Workspace and documentation | GitHub
- **📋 Linear** - Project management and issue tracking | GitHub
- **💰 Stripe** - Payment processing platform | GitHub
- **💳 PayPal** - Payment services integration | GitHub
- **📊 HubSpot** - CRM and marketing platform | GitHub
### 🔍 Search & AI
🔍 Search Engines
- **🔍 Exa** - Search engine made for AIs | GitHub
- **🌐 Tavily** - Search engine for AI agents | GitHub
- **🔎 Kagi Search** - Privacy-focused search API | GitHub
- **🌟 Perplexity** - Real-time web research API | GitHub
🤖 AI & ML Platforms
- **🧠 OpenAI** - GPT models and AI services | GitHub
- **🎯 Anthropic** - Claude AI integration | GitHub
- **🔥 Logfire** - OpenTelemetry traces and metrics | GitHub
- **📊 Langfuse** - LLM observability and analytics | GitHub
- **🎨 ElevenLabs** - Text-to-speech AI platform | GitHub
---
## 🌍 Community Servers
A growing ecosystem of community-developed servers:
### 🌟 Popular Community Servers
| Server | Description | Language | Repository | Website |
|--------|-------------|----------|------------|---------|
| **🔍 Brave Search** | Web search using Brave API | TypeScript | GitHub | Brave |
| **🌐 WhatsApp MCP** | WhatsApp integration server | TypeScript | GitHub | Demo |
| **🎨 Figma Context** | Figma design context integration | TypeScript | GitHub | Figma |
| **🔄 n8n Nodes** | Workflow automation integration | TypeScript | GitHub | n8n |
| **🌐 Browser MCP** | Browser automation and control | TypeScript | GitHub | Demo |
| **📊 Awesome MCP ZH** | Chinese MCP resources collection | - | GitHub | Website |
### 📊 Data & Analytics
🗄️ Database Servers
- **🐘 PostgreSQL** - Multiple implementations for PostgreSQL | GitHub
- **🟢 MongoDB** - NoSQL database integration | GitHub
- **🔴 Redis** - In-memory data structure store | GitHub
- **🦆 DuckDB** - Analytical database engine | GitHub
- **📊 InfluxDB** - Time series database | GitHub
- **🌐 Neo4j** - Graph database platform | GitHub
- **❄️ Snowflake** - Cloud data warehouse | GitHub
📈 Analytics & Visualization
- **📊 Chart.js** - Data visualization library | GitHub
- **📈 Vega-Lite** - Grammar of interactive graphics | GitHub
- **📊 QuickChart** - Chart generation service | GitHub
- **📉 Grafana** - Monitoring and observability | GitHub
- **🔍 Elasticsearch** - Search and analytics | GitHub
### 🌐 Web & APIs
🌐 Web Services
- **🌐 Fetch** - Web content fetching and conversion | GitHub
- **🕷️ Playwright** - Browser automation | GitHub
- **🔍 SearXNG** - Privacy-respecting search engine | GitHub
- **📸 ScreenshotOne** - Website screenshot service | GitHub
- **🌐 Firecrawl** - Web scraping and data extraction | GitHub
🔗 API Integration
- **🔗 OpenAPI** - REST API integration | GitHub
- **📡 GraphQL** - GraphQL API support | GitHub
- **🔌 Zapier** - Connect 8,000+ apps | GitHub
- **🔄 Make** - Automation platform integration | GitHub
- **🌐 Postman** - API development platform | GitHub
### 🛠️ Development Tools
💻 Code & Development
- **🔧 Git** - Version control operations | GitHub
- **🐙 GitHub** - GitHub API integration | GitHub
- **🦊 GitLab** - GitLab platform integration | GitHub
- **📝 VS Code** - Editor integration | GitHub
- **🎯 JetBrains** - IDE integration | GitHub
- **🔍 Language Server** - LSP integration | GitHub
🧪 Testing & Quality
- **🧪 Jest** - JavaScript testing framework | GitHub
- **🔍 ESLint** - Code linting and quality | GitHub
- **🛡️ Semgrep** - Static analysis security | GitHub
- **🔒 Snyk** - Security vulnerability scanning | GitHub
- **📊 SonarQube** - Code quality analysis | GitHub
### 📱 Productivity & Office
📝 Documentation & Notes
- **📝 Obsidian** - Knowledge management | GitHub
- **📓 Notion** - Workspace and notes | GitHub
- **📋 Markdown** - Markdown processing | GitHub
- **📄 Pandoc** - Document conversion | GitHub
- **📚 Confluence** - Team documentation | GitHub
📅 Calendar & Tasks
- **📅 Google Calendar** - Calendar management | GitHub
- **✅ Todoist** - Task management | GitHub
- **📋 Trello** - Project boards | GitHub
- **📊 Asana** - Team project management | GitHub
- **🎯 Linear** - Issue tracking | GitHub
### 🎨 Media & Content
🎨 Image & Video
- **🎨 DALL-E** - AI image generation | GitHub
- **🖼️ Stable Diffusion** - Image generation | GitHub
- **📹 FFmpeg** - Video processing | GitHub
- **🎬 YouTube** - Video platform integration | GitHub
- **📸 Unsplash** - Stock photography | GitHub
🎵 Audio & Music
- **🎵 Spotify** - Music streaming platform | GitHub
- **🎙️ Podcast** - Podcast management | GitHub
- **🔊 Audio Processing** - Audio manipulation | GitHub
- **🎼 Music Theory** - Musical analysis tools | GitHub
---
## 🛠️ Frameworks & Tools
### 🏗️ Server Frameworks
🚀 TypeScript Frameworks
- **⚡ FastMCP** - Fast TypeScript framework | GitHub
- **🎯 EasyMCP** - Simple TypeScript framework | GitHub
- **🏗️ MCP-Framework** - Elegant TypeScript framework with CLI | GitHub
- **📝 Template MCP Server** - CLI tool for new projects | GitHub
🐍 Python Frameworks
- **🌸 Spring AI MCP Server** - Spring Boot auto-configuration
- **⚡ FastAPI to MCP** - Auto-generate MCP from FastAPI
- **🔧 Quarkus MCP Server SDK** - Java framework integration
- **🦀 Rust Frameworks** - Rust-based MCP implementations
- **☕ Java Frameworks** - Enterprise Java solutions
- **🔷 Go Frameworks** - High-performance Go servers
- **🔶 C++ Frameworks** - Native performance solutions
### 🔧 Development Tools
🛠️ CLI Tools
- **🔍 mcp-cli** - CLI inspector for MCP servers | GitHub
- **📦 mcp-get** - Command line tool for installing servers | GitHub
- **🎯 mcpm** - MCP Manager (Homebrew-like service) | GitHub
- **🔧 mcp-manager** - Web UI for managing MCP servers | GitHub
🖥️ GUI Applications
- **🎨 MCP Inspector** - Visual testing tool for servers | GitHub
- **🖥️ MCPHub** - Desktop app for discovering servers | GitHub
- **🎯 MCP Router** - Windows/macOS management app | GitHub
- **🔧 mcp-dockmaster** - UI for server management | GitHub
### 🌐 Hosting & Deployment
☁️ Cloud Platforms
- **☁️ mcp.run** - Hosted registry and control plane | Website
- **🌐 MCPVerse** - Portal for creating hosted servers | Website
- **🔧 Smithery** - Registry of MCP servers | Website
- **📊 PulseMCP** - Community hub and newsletter | Website
🐳 Containerization
- **🐳 Docker Images** - Pre-built server containers
- **☸️ Kubernetes** - Orchestration for MCP servers
- **🔧 Helm Charts** - Kubernetes deployment charts
- **🚀 Docker Compose** - Multi-container deployments
---
## 📖 Resources & Learning
### 📚 Documentation
📖 Official Documentation
- **📖 MCP Documentation** - Complete user guide
- **🔧 MCP Specification** - Technical specification
- **🚀 Quickstart Guide** - Get started quickly
- **🎯 Example Servers** - Reference implementations
🎓 Tutorials & Guides
- **🏗️ Building MCP with LLMs** - AI-assisted development
- **🐛 Debugging Guide** - Troubleshooting tips
- **🔍 Inspector Tutorial** - Testing servers
### 🌟 Community Resources
🗂️ Awesome Lists
- **⭐ Awesome MCP Servers by punkpeye** - Curated list with website
- **⭐ Awesome MCP Servers by wong2** - Community curated list
- **⭐ Awesome MCP Servers by appcypher** - Another curated collection
- **🔐 Awesome Remote MCP Servers** - Remote servers with auth
💬 Community Platforms
- **💬 Discord Server** - Community discussions
- **🗨️ GitHub Discussions** - Technical discussions
- **📱 Reddit r/mcp** - Community forum
- **🐦 Twitter/X Community** - Latest updates
### 🎥 Learning Materials
🎬 Videos & Workshops
- **🎯 Building Agents with MCP Workshop** - AI Engineer Summit
- **📺 MCP Tutorial Series** - Step-by-step guides
- **🎪 Conference Talks** - Expert presentations
📝 Articles & Blogs
- **📰 Anthropic Engineering Blog** - Official updates
- **📝 Medium Articles** - Community tutorials
- **📖 Dev.to Posts** - Developer experiences
---
## 🔒 Security & Trust
### 🛡️ Security Principles
MCP is built with security as a core principle:
1. **👤 User Consent and Control**
- Users must explicitly consent to all data access and operations
- Users retain control over what data is shared and actions taken
- Clear UIs for reviewing and authorizing activities
2. **🔐 Data Privacy**
- Explicit user consent before exposing data to servers
- No transmission of resource data without consent
- Appropriate access controls and data protection
3. **🛠️ Tool Safety**
- Tools represent arbitrary code execution - treated with caution
- Explicit user consent before invoking any tool
- Users understand what each tool does before authorization
4. **🤖 LLM Sampling Controls**
- Users explicitly approve LLM sampling requests
- Control over sampling occurrence, prompts, and results
- Limited server visibility into prompts
### 🔐 Authentication & Authorization
🔑 OAuth 2.0 Integration
- **🔐 Standardized Authentication** - OAuth 2.0 for secure access
- **🎫 Token Management** - Server-controlled token handling
- **🔒 Secure Flows** - Web-based authorization flows
- **🛡️ Permission Management** - Granular access controls
🛡️ Security Best Practices
- **✅ Input Validation** - Validate all user inputs
- **🔒 Access Controls** - Implement appropriate permissions
- **📊 Audit Logging** - Track all operations
- **⏱️ Rate Limiting** - Prevent abuse
- **🔐 Encryption** - Secure data in transit and at rest
---
## 🚀 Getting Started
### 🎯 Quick Start
1. **📖 Read the Documentation**```bash
# Visit the official documentation
open https://modelcontextprotocol.io
```
2. **🔧 Install an SDK**```bash
# TypeScript
npm install @modelcontextprotocol/sdk
# Python
pip install mcp
# Java (Maven)
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp</artifactId>
</dependency>
```
3. **🏗️ Create Your First Server**```bash
# Using the TypeScript template
npx create-mcp-server my-server
# Using Python
python -m mcp.server.stdio my_server.py
```
4. **🧪 Test with Inspector**```bash
# Install and run the inspector
npx @modelcontextprotocol/inspector
```
### 📚 Learning Path
1. **🎯 Beginner**: Start with the Quickstart Guide
2. **🔧 Intermediate**: Build a custom server using the SDK Documentation
3. **🚀 Advanced**: Explore Advanced Patterns and contribute to the ecosystem
### 🛠️ Development Setup
🔧 Development Environment```bash
# Clone the main repository
git clone https://github.com/modelcontextprotocol/servers.git
cd servers
# Install dependencies
npm install
# Run tests
npm test
# Start development server
npm run dev
🧪 Testing Your Server```bash
Use the MCP Inspector
npx @modelcontextprotocol/inspector
Or test with Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["path/to/your/server.js"]
}
}
}
```
