From 2ea87434703e5ed75098dbdc475184df1b28ddfe Mon Sep 17 00:00:00 2001 From: Zack Lee Date: Tue, 19 Nov 2024 09:24:37 -0500 Subject: [PATCH 1/7] updated landing page --- docs/guides/quickstart.mdx | 232 +++++++++++++++++++++++-------------- introduction.mdx | 14 --- 2 files changed, 146 insertions(+), 100 deletions(-) diff --git a/docs/guides/quickstart.mdx b/docs/guides/quickstart.mdx index 2234e5a..0f590b5 100644 --- a/docs/guides/quickstart.mdx +++ b/docs/guides/quickstart.mdx @@ -3,32 +3,62 @@ title: "Quickstart" description: "Get started with MCP in less than 5 minutes" --- -Give Claude desktop superpowers by connecting it to your local computer! This guide will show you how to set up Model Context Protocol (MCP) and experience its magic in just 5 minutes. - - -MCP connects Claude to external data sources and tools. In this guide, we'll give Claude the ability to: -- Take screenshots and analyze them -- Control window arrangement -- Execute local automation scripts - -And it does this all securely - Claude can only access what you explicitly allow through MCP servers. + +MCP is currently in developer preview and only supports connecting to local servers running on your machine. Remote connections are not yet supported. This feature is only available in the Claude Desktop app, not the Claude web interface (claude.ai). +Give the Claude Desktop app the ability to interact with local data sources and tools! This guide will show you how to set up Model Context Protocol (MCP) and experience its capabilities in just 5 minutes. + +MCP is a protocol that enables secure connections between the Claude Desktop app and local services. In this quickstart guide, you'll learn how to: + +- Set up a local SQLite database +- Connect Claude Desktop to it through MCP +- Query and analyze your data securely + +## How MCP Works + +MCP enables secure, controlled interactions between the Claude Desktop app and local services through a well-defined protocol: + +```mermaid +flowchart LR + subgraph "Your Computer" + CD[Claude Desktop] + MCP[MCP Server] + DB[(SQLite DB)] + + CD <-->|MCP Protocol| MCP + MCP <-->|Local Access| DB + end + + style CD fill:#e1e1e1 + style MCP fill:#d4e6ff + style DB fill:#d4ffe1 +``` + +1. **MCP Servers**: Small programs that expose specific capabilities (like database access) through a standardized interface +2. **Protocol**: A structured way for Claude Desktop to: + - Discover available capabilities + - Request actions securely + - Receive results and updates +3. **Local Only**: All communication happens entirely on your machine - no data leaves your computer + ## Prerequisites - macOS (Windows/Linux guides coming soon) - Node.js v18 or higher (`node --version` to check) - Git (`git --version` to check) -- [Claude desktop app](https://claude.ai/download) installed +- [Claude Desktop app](https://claude.ai/download) installed +- SQLite (`sqlite3 --version` to check) ```bash # Using Homebrew -brew install node git +brew install node git sqlite3 # Or download directly: # Node.js: https://nodejs.org # Git: https://git-scm.com +# SQLite: https://www.sqlite.org/download.html ``` @@ -36,7 +66,7 @@ brew install node git - Let's start by getting some pre-built MCP servers that Claude can use: + Let's start by getting the pre-built MCP servers: ```bash # Clone the example servers @@ -50,9 +80,31 @@ brew install node git # Make servers available globally npm install -g ``` + + This makes the MCP servers available as command-line tools that Claude Desktop can launch. - + + Let's create a simple SQLite database for testing: + + ```bash + # Create a new SQLite database + sqlite3 ~/test.db < + + Open your Claude Desktop App configuration: ```bash @@ -64,94 +116,101 @@ brew install node git ```json { "mcpServers": { - "osascript": { - "command": "mcp-server-osascript", + "sqlite": { + "command": "mcp-server-sqlite", + "args": ["/Users/YOUR_USERNAME/test.db"] } } } ``` + This tells Claude Desktop: + 1. There's an MCP server named "sqlite" + 2. Launch it using the `mcp-server-sqlite` command + 3. Connect it to your test database + 4. Provide necessary environment variables + Save and **restart Claude Desktop App**. ## Test it out -Let's verify everything is working with a simple example. Try sending this prompt to Claude: +Let's verify everything is working. Try sending this prompt to Claude Desktop: ``` -Can you take a screenshot of my desktop and describe what you see? +Can you connect to my SQLite database and tell me what products are available and their prices? ``` -Claude will: - -1. Request permission to take a screenshot -2. Capture your screen through the MCP server -3. Analyze and describe the screenshot +Claude Desktop will: +1. Connect to the SQLite MCP server +2. Query your local database +3. Format and present the results - Example Claude conversation showing a screenshot analysis + Example Claude Desktop conversation showing database query results - -The first time you use screenshot features, macOS will ask for permissions: -- Screen Recording (for screenshots) -- Automation (for window control) -You'll need to grant these to Claude.app in System Settings. - + +## What's happening under the hood? + +When you interact with Claude Desktop using MCP: + +1. **Server Discovery**: Claude Desktop loads your configured MCP servers on startup +2. **Protocol Handshake**: When you ask about data, Claude Desktop: + - Identifies which MCP server can help (sqlite in this case) + - Negotiates capabilities through the MCP protocol + - Establishes a secure local connection + +3. **Interaction Flow**: + ```mermaid + sequenceDiagram + participant C as Claude Desktop + participant M as MCP Server + participant D as SQLite DB + + C->>M: Initialize connection + M-->>C: Available capabilities + + C->>M: Query request + M->>D: SQL query + D-->>M: Results + M-->>C: Formatted results + ``` + +4. **Security**: + - MCP servers only expose specific, controlled capabilities + - All communication is local to your machine + - Claude Desktop requires user confirmation for sensitive operations ## Try these examples Now that MCP is working, try these increasingly powerful examples: - + ``` - Could you analyze my open windows and tell me: - - How many windows I have open - - Which apps are running - - If any windows look cluttered + What's the average price of all products in the database? ``` - + ``` - Could you help organize my windows? I'd like: - - Browser on the left half - - VSCode on the right half + Can you analyze the price distribution and suggest any pricing optimizations? ``` - + ``` - I often need this window layout for coding: - - VSCode taking up the left 60% - - Terminal in the top right - - Browser in the bottom right - Could you create an AppleScript to automate this? + Could you help me design and create a new table for storing customer orders? ``` -## What just happened? - -Let's break down the magic: - -1. When you installed the `osascript` server, you gave Claude a way to: - - Take screenshots (see what you see) - - Run AppleScript (control your windows) - - Automate macOS tasks - -2. The MCP protocol lets Claude: - - Request these actions securely - - Get results back in real-time - - Chain actions together intelligently - -3. All of this happens locally on your machine - no data leaves your computer! - ## Add more capabilities -Want to give Claude even more superpowers? Add these servers to your configuration: +Want to give Claude Desktop more local integration capabilities? Add these servers to your configuration: + - Add this to your config to let Claude read and analyze files: + Add this to your config to let Claude Desktop read and analyze files: ```json "tee": { "command": "mcp-server-tee", @@ -163,8 +222,8 @@ Want to give Claude even more superpowers? Add these servers to your configurati ``` - - Connect Claude to your PostgreSQL database: + + Connect Claude Desktop to your PostgreSQL database: ```json "postgres": { "command": "mcp-server-postgres", @@ -175,23 +234,14 @@ Want to give Claude even more superpowers? Add these servers to your configurati } ``` - - - Enable web automation capabilities: - ```json - "puppeteer": { - "command": "mcp-server-puppeteer", - } - ``` - ## Troubleshooting - + 1. Check if MCP is enabled: - - Click the 🔌 icon in Claude + - Click the 🔌 icon in Claude Desktop - You should see your configured servers 2. Verify your config: @@ -199,21 +249,27 @@ Want to give Claude even more superpowers? Add these servers to your configurati cat ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` - 3. Restart Claude completely: + 3. Restart Claude Desktop completely: - Quit the app (not just close the window) - Start it again - - Run this command to see Claude's logs: - ```bash - tail -f ~/Claude.log - ``` + + 1. Check Claude Desktop's logs: + ```bash + tail -f ~/Claude.log + ``` - Common fixes: - - Check `HOME` env variable in your config - - Grant missing permissions in System Settings - - Try running example commands manually in Terminal + 2. Verify database access: + ```bash + # Test database connection + sqlite3 ~/test.db ".tables" + ``` + + 3. Common fixes: + - Check file paths in your config + - Verify database file permissions + - Ensure SQLite is installed properly @@ -221,7 +277,7 @@ Want to give Claude even more superpowers? Add these servers to your configurati - Create your own MCP integrations to give Claude new capabilities. + Create your own MCP servers to give Claude Desktop new capabilities. @@ -233,3 +289,7 @@ Want to give Claude even more superpowers? Add these servers to your configurati [Join us →](/community) + + +Remember: MCP is in developer preview and currently only supports local servers. The examples and capabilities shown here are only available in the Claude Desktop app, not the Claude web interface. + \ No newline at end of file diff --git a/introduction.mdx b/introduction.mdx index 209d35c..ce585d0 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -31,20 +31,6 @@ Choose the path that best fits your needs: > Create a simple MCP server in Python to understand the basics - - Add MCP support to your TypeScript/JavaScript LLM application - - - Add MCP support to your Python LLM application - ## Explore MCP From 8b2d79502ffb01232db102fd917240b5661089c2 Mon Sep 17 00:00:00 2001 From: Zack Lee Date: Tue, 19 Nov 2024 09:33:08 -0500 Subject: [PATCH 2/7] fixed logo --- logo/dark.svg | 26 ++++++++++---------------- logo/light.svg | 15 +++++---------- 2 files changed, 15 insertions(+), 26 deletions(-) diff --git a/logo/dark.svg b/logo/dark.svg index b5db00b..8f3cb4a 100644 --- a/logo/dark.svg +++ b/logo/dark.svg @@ -1,17 +1,11 @@ - - - - - - - - - - - - - - - - + + + + + + + + + + diff --git a/logo/light.svg b/logo/light.svg index 0015bd1..6e304fa 100644 --- a/logo/light.svg +++ b/logo/light.svg @@ -1,11 +1,6 @@ - - - - - - - - - - + + + + + From 84f9f52f9d17cd449ad8fc895749912481cc68ae Mon Sep 17 00:00:00 2001 From: Zachary Lee Date: Tue, 19 Nov 2024 09:35:02 -0500 Subject: [PATCH 3/7] Update docs/guides/quickstart.mdx Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com> --- docs/guides/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/quickstart.mdx b/docs/guides/quickstart.mdx index 0f590b5..2b11974 100644 --- a/docs/guides/quickstart.mdx +++ b/docs/guides/quickstart.mdx @@ -9,7 +9,7 @@ MCP is currently in developer preview and only supports connecting to local serv Give the Claude Desktop app the ability to interact with local data sources and tools! This guide will show you how to set up Model Context Protocol (MCP) and experience its capabilities in just 5 minutes. -MCP is a protocol that enables secure connections between the Claude Desktop app and local services. In this quickstart guide, you'll learn how to: +MCP is a protocol that enables secure connections between clients, such as Claude Desktop app, and local services. In this quickstart guide, you'll learn how to: - Set up a local SQLite database - Connect Claude Desktop to it through MCP From 4e72a569ff4e38238f9bae40ea6e91984a45dc6c Mon Sep 17 00:00:00 2001 From: Zack Lee Date: Tue, 19 Nov 2024 09:49:09 -0500 Subject: [PATCH 4/7] fixes --- docs/guides/quickstart.mdx | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/guides/quickstart.mdx b/docs/guides/quickstart.mdx index 2b11974..3808d88 100644 --- a/docs/guides/quickstart.mdx +++ b/docs/guides/quickstart.mdx @@ -3,11 +3,15 @@ title: "Quickstart" description: "Get started with MCP in less than 5 minutes" --- - -MCP is currently in developer preview and only supports connecting to local servers running on your machine. Remote connections are not yet supported. This feature is only available in the Claude Desktop app, not the Claude web interface (claude.ai). +Give the Claude Desktop app the ability to interact with local data sources and tools! This guide will show you how to set up Model Context Protocol (MCP) and experience its capabilities in just 5 minutes. + + +While this guide focuses on using Claude Desktop as an example MCP client, the protocol is open and can be implemented by any application. IDEs, AI tools, and other software can all act as MCP clients to access local services in a standardized way. -Give the Claude Desktop app the ability to interact with local data sources and tools! This guide will show you how to set up Model Context Protocol (MCP) and experience its capabilities in just 5 minutes. + +Claude Desktop's MCP support is currently in developer preview and only supports connecting to local servers running on your machine. Remote connections are not yet supported. MCP integration is only available in the Claude Desktop app, not the Claude web interface (claude.ai). + MCP is a protocol that enables secure connections between clients, such as Claude Desktop app, and local services. In this quickstart guide, you'll learn how to: @@ -17,26 +21,22 @@ MCP is a protocol that enables secure connections between clients, such as Claud ## How MCP Works -MCP enables secure, controlled interactions between the Claude Desktop app and local services through a well-defined protocol: +MCP is an open protocol that enables secure, controlled interactions between any compatible client application (like Claude Desktop, IDEs, or other AI tools) and local services: ```mermaid flowchart LR subgraph "Your Computer" - CD[Claude Desktop] + Client["MCP Client\n(e.g. Claude Desktop)"] MCP[MCP Server] DB[(SQLite DB)] - CD <-->|MCP Protocol| MCP + Client <-->|MCP Protocol| MCP MCP <-->|Local Access| DB end - - style CD fill:#e1e1e1 - style MCP fill:#d4e6ff - style DB fill:#d4ffe1 ``` 1. **MCP Servers**: Small programs that expose specific capabilities (like database access) through a standardized interface -2. **Protocol**: A structured way for Claude Desktop to: +2. **Protocol**: An open standard that allows any MCP client to: - Discover available capabilities - Request actions securely - Receive results and updates @@ -288,8 +288,4 @@ Want to give Claude Desktop more local integration capabilities? Add these serve Share your MCP creations and connect with other developers. [Join us →](/community) - - - -Remember: MCP is in developer preview and currently only supports local servers. The examples and capabilities shown here are only available in the Claude Desktop app, not the Claude web interface. - \ No newline at end of file + \ No newline at end of file From 47bfa61c8907c8ad1ef06c762d1ce2812febc171 Mon Sep 17 00:00:00 2001 From: Zack Lee Date: Tue, 19 Nov 2024 09:53:57 -0500 Subject: [PATCH 5/7] resized logo --- logo/dark.svg | 9 ++------- logo/light.svg | 4 ++-- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/logo/dark.svg b/logo/dark.svg index 8f3cb4a..897c1e3 100644 --- a/logo/dark.svg +++ b/logo/dark.svg @@ -1,11 +1,6 @@ - + - - - - - - + diff --git a/logo/light.svg b/logo/light.svg index 6e304fa..2ecc0dd 100644 --- a/logo/light.svg +++ b/logo/light.svg @@ -1,6 +1,6 @@ - + - + From 7e6bed626eaa5c0af5be2ceec486a85776822e8a Mon Sep 17 00:00:00 2001 From: Zack Lee Date: Tue, 19 Nov 2024 10:04:48 -0500 Subject: [PATCH 6/7] resized logo --- docs/guides/first-server-python.mdx | 2 +- docs/guides/first-server-ts.mdx | 2 +- docs/guides/quickstart.mdx | 26 ++++++++++++++++++++++++-- mint.json | 17 +++++++---------- 4 files changed, 33 insertions(+), 14 deletions(-) diff --git a/docs/guides/first-server-python.mdx b/docs/guides/first-server-python.mdx index 7c512a2..3068ccb 100644 --- a/docs/guides/first-server-python.mdx +++ b/docs/guides/first-server-python.mdx @@ -1,5 +1,5 @@ --- -title: "Your First MCP Server (Python)" +title: "Python" description: "Create a simple MCP server in Python in 15 minutes" --- diff --git a/docs/guides/first-server-ts.mdx b/docs/guides/first-server-ts.mdx index d3e0656..2615856 100644 --- a/docs/guides/first-server-ts.mdx +++ b/docs/guides/first-server-ts.mdx @@ -1,5 +1,5 @@ --- -title: "Your First MCP Server (TypeScript)" +title: "TypeScript" description: "Create a simple MCP server in TypeScript in 15 minutes" --- diff --git a/docs/guides/quickstart.mdx b/docs/guides/quickstart.mdx index 3808d88..277b000 100644 --- a/docs/guides/quickstart.mdx +++ b/docs/guides/quickstart.mdx @@ -19,7 +19,7 @@ MCP is a protocol that enables secure connections between clients, such as Claud - Connect Claude Desktop to it through MCP - Query and analyze your data securely -## How MCP Works +## How MCP works MCP is an open protocol that enables secure, controlled interactions between any compatible client application (like Claude Desktop, IDEs, or other AI tools) and local services: @@ -42,6 +42,28 @@ flowchart LR - Receive results and updates 3. **Local Only**: All communication happens entirely on your machine - no data leaves your computer +## MCP clients + +While this guide demonstrates MCP using Claude Desktop, several other applications support MCP integration: + + + + A high-performance, multiplayer code editor with built-in MCP support for AI-powered coding assistance + + + + Code intelligence platform featuring MCP integration for enhanced code search and analysis capabilities + + + +Each client may implement MCP features differently or support different capabilities. Check their respective documentation for specific setup instructions and supported features. + ## Prerequisites - macOS (Windows/Linux guides coming soon) @@ -273,7 +295,7 @@ Want to give Claude Desktop more local integration capabilities? Add these serve -## Next Steps +## Next steps diff --git a/mint.json b/mint.json index 620d536..e39b06e 100644 --- a/mint.json +++ b/mint.json @@ -12,14 +12,9 @@ "light": "#FAFAFA", "dark": "#09090b" }, - "topbarLinks": [ - { - "name": "Support", - "url": "mailto:mcp-coc@anthropic.com" - } - ], + "topbarLinks": [], "topbarCtaButton": { - "name": "Github", + "name": "GitHub", "url": "https://github.com/modelcontextprotocol" }, "tabs": [ @@ -32,7 +27,7 @@ { "name": "Documentation", "icon": "book-open-cover", - "url": "https://mintlify.com/docs" + "url": "https://modelcontextprotocol.io" }, { "name": "Python SDK", @@ -48,9 +43,11 @@ "navigation": [ { "group": "Get Started", + "pages": ["introduction", "docs/guides/quickstart"] + }, + { + "group": "Your First MCP Server", "pages": [ - "introduction", - "docs/guides/quickstart", "docs/guides/first-server-python", "docs/guides/first-server-ts" ] From b9b72c97768700f89e0e50d27043726a704ed82e Mon Sep 17 00:00:00 2001 From: Zack Lee Date: Tue, 19 Nov 2024 12:55:12 -0500 Subject: [PATCH 7/7] improvements --- docs/guides/quickstart.mdx | 66 +++++++++++++++++++++++++++----------- mint.json | 4 +++ 2 files changed, 51 insertions(+), 19 deletions(-) diff --git a/docs/guides/quickstart.mdx b/docs/guides/quickstart.mdx index 277b000..7091741 100644 --- a/docs/guides/quickstart.mdx +++ b/docs/guides/quickstart.mdx @@ -3,7 +3,11 @@ title: "Quickstart" description: "Get started with MCP in less than 5 minutes" --- -Give the Claude Desktop app the ability to interact with local data sources and tools! This guide will show you how to set up Model Context Protocol (MCP) and experience its capabilities in just 5 minutes. +MCP is a protocol that enables secure connections between clients, such as Claude Desktop app, and local services. In this quickstart guide, you'll learn how to: + +- Set up a local SQLite database +- Connect Claude Desktop to it through MCP +- Query and analyze your data securely While this guide focuses on using Claude Desktop as an example MCP client, the protocol is open and can be implemented by any application. IDEs, AI tools, and other software can all act as MCP clients to access local services in a standardized way. @@ -13,34 +17,58 @@ While this guide focuses on using Claude Desktop as an example MCP client, the p Claude Desktop's MCP support is currently in developer preview and only supports connecting to local servers running on your machine. Remote connections are not yet supported. MCP integration is only available in the Claude Desktop app, not the Claude web interface (claude.ai). -MCP is a protocol that enables secure connections between clients, such as Claude Desktop app, and local services. In this quickstart guide, you'll learn how to: - -- Set up a local SQLite database -- Connect Claude Desktop to it through MCP -- Query and analyze your data securely - ## How MCP works -MCP is an open protocol that enables secure, controlled interactions between any compatible client application (like Claude Desktop, IDEs, or other AI tools) and local services: +MCP (Model Context Protocol) is an open protocol that enables secure, controlled interactions between AI applications and local resources on your computer. Let's break down how it works, then look at how we'll use it in this guide. + +### General Architecture +At its core, MCP follows a client-server architecture where multiple services can connect to any compatible client: ```mermaid flowchart LR subgraph "Your Computer" - Client["MCP Client\n(e.g. Claude Desktop)"] - MCP[MCP Server] - DB[(SQLite DB)] + Client["MCP Clients\n(Claude, IDEs, Tools)"] + S1["MCP Server A"] + S2["MCP Server B"] + S3["MCP Server C"] - Client <-->|MCP Protocol| MCP - MCP <-->|Local Access| DB + Client <-->|"MCP Protocol"| S1 + Client <-->|"MCP Protocol"| S2 + Client <-->|"MCP Protocol"| S3 + + S1 <--> R1[("Local\nResource A")] + S2 <--> R2[("Local\nResource B")] + S3 <--> R3[("Local\nResource C")] end ``` -1. **MCP Servers**: Small programs that expose specific capabilities (like database access) through a standardized interface -2. **Protocol**: An open standard that allows any MCP client to: - - Discover available capabilities - - Request actions securely - - Receive results and updates -3. **Local Only**: All communication happens entirely on your machine - no data leaves your computer +- **MCP Clients**: Applications like Claude Desktop, IDEs, or AI tools that want to access local resources +- **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized MCP protocol +- **Local Resources**: Your computer's resources (databases, files, services) that MCP servers can securely access + +### In This Guide + +For this quickstart, we'll implement a focused example using SQLite: + +```mermaid +flowchart LR + subgraph "Your Computer" + direction LR + Claude["Claude Desktop"] + MCP["SQLite MCP Server"] + DB[(SQLite Database\n~/test.db)] + + Claude <-->|"MCP Protocol\n(Queries & Results)"| MCP + MCP <-->|"Local Access\n(SQL Operations)"| DB + end +``` + +1. Claude Desktop acts as our MCP client +2. A SQLite MCP Server provides secure database access +3. Your local SQLite database stores the actual data + +All communication happens entirely on your machine - no data leaves your computer. The MCP protocol ensures that Claude Desktop can only perform approved database operations through well-defined interfaces. +This gives you a secure way to let Claude analyze and interact with your local data while maintaining complete control over what it can access. ## MCP clients diff --git a/mint.json b/mint.json index e39b06e..84964b2 100644 --- a/mint.json +++ b/mint.json @@ -21,6 +21,10 @@ { "name": "API Reference", "url": "api-reference" + }, + { + "name": "Specification", + "url": "specification" } ], "anchors": [