MCP Container

mcp-claude-desktop-guide

Comprehensive guide to MCP (Model Context Protocol) with Claude Desktop configuration examples for GitHub and Supabase integration

GitHub

GitHubスター

1

ユーザー評価

未評価

フォーク

0

イシュー

0

閲覧数

0

お気に入り

0

README
MCP (Model Context Protocol) Complete Guide

Welcome to the comprehensive guide for Model Context Protocol (MCP) with Claude Desktop integration examples. This repository provides everything you need to understand MCP, configure Claude Desktop, and connect to services like GitHub and Supabase.

Table of Contents
What is MCP?

Model Context Protocol (MCP) is an open standard that enables secure connections between AI assistants (like Claude) and external data sources and tools. It allows Claude to interact with various services through a standardized interface.

Key Features
  • Standardized Communication: Uses JSON-RPC 2.0 for client-server communication
  • Secure: Built-in authentication and authorization mechanisms
  • Extensible: Supports custom tools and data sources
  • Real-time: Enables live data access and tool execution
  • Bidirectional: Allows both data retrieval and action execution
How MCP Works
┌─────────────┐    JSON-RPC    ┌─────────────┐    HTTP/API    ┌─────────────┐
│   Claude    │ ◄────────────► │ MCP Server  │ ◄────────────► │  External   │
│  (Client)   │                │             │                │  Service    │
└─────────────┘                └─────────────┘                └─────────────┘
  1. Claude acts as the MCP client
  2. MCP Server translates between MCP protocol and external service APIs
  3. External Service (GitHub, Supabase, etc.) provides the actual functionality
JSON-RPC Protocol

MCP uses JSON-RPC 2.0 for communication. Here's how the protocol works:

Request Format
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tools/call",
  "params": {
    "name": "github:create_repository",
    "arguments": {
      "name": "my-new-repo",
      "description": "A new repository",
      "private": false
    }
  }
}
Response Format

Success Response:

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Repository created successfully"
      }
    ]
  }
}

Error Response:

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "Repository already exists",
    "data": {
      "details": "A repository with this name already exists"
    }
  }
}
Common Methods
  • initialize - Establish connection
  • tools/list - Get available tools
  • tools/call - Execute a tool
  • resources/list - Get available resources
  • resources/read - Read resource content
Claude Desktop Configuration

Claude Desktop uses a configuration file to define MCP server connections. The configuration file location varies by operating system:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Basic Configuration Structure
{
  "mcpServers": {
    "server-name": {
      "command": "path-to-executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
GitHub Integration
Prerequisites
  1. GitHub Personal Access Token with appropriate permissions
  2. MCP GitHub Server (typically @modelcontextprotocol/server-github)
Installation
npm install -g @modelcontextprotocol/server-github
Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN_HERE"
      }
    }
  }
}
Environment Variables

Create a .env file or set these environment variables:

# Replace with your actual GitHub token
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GitHub Token Permissions

Your GitHub token needs these scopes:

  • repo - Full repository access
  • workflow - GitHub Actions workflow access
  • read:org - Organization read access
  • user:email - Email access
Supabase Integration
Prerequisites
  1. Supabase Project with API credentials
  2. MCP Supabase Server (typically @modelcontextprotocol/server-supabase)
Installation
npm install -g @modelcontextprotocol/server-supabase
Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-supabase"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_ANON_KEY": "YOUR_SUPABASE_ANON_KEY"
      }
    }
  }
}
Environment Variables
# Replace with your actual Supabase credentials
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Finding Your Supabase Credentials
  1. Go to your Supabase Dashboard
  2. Select your project
  3. Go to Settings → API
  4. Copy:
    • Project URL → SUPABASE_URL
    • Project API keys → anon/public → SUPABASE_ANON_KEY
Complete Configuration Example

Here's a complete claude_desktop_config.json file with both GitHub and Supabase:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    },
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-supabase"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project-id.supabase.co",
        "SUPABASE_ANON_KEY": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlvdXItcHJvamVjdC1pZCIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjc3NTU2ODAwLCJleHAiOjE5OTMxMzI4MDB9.your-signature-here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
Available MCP Servers

Here are some popular MCP servers you can add:

File System Access
"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
}
Web Search (Brave)
"brave-search": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
  }
}
Slack Integration
"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
    "SLACK_TEAM_ID": "YOUR_TEAM_ID"
  }
}
PostgreSQL Database
"postgres": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres"],
  "env": {
    "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/dbname"
  }
}
Troubleshooting
Common Issues

1. MCP Server Not Found

# Install the MCP server globally
npm install -g @modelcontextprotocol/server-github

2. Authentication Errors

  • Verify your API tokens are correct
  • Check token permissions/scopes
  • Ensure environment variables are properly set

3. Configuration File Location Make sure you're editing the correct config file:

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

4. JSON Syntax Errors

  • Use a JSON validator to check your configuration
  • Ensure proper comma placement
  • Check for missing quotes
Testing Your Configuration
  1. Restart Claude Desktop after making configuration changes
  2. Check the Tools Menu in Claude Desktop - you should see new tools
  3. Test a Simple Command like asking Claude to list your GitHub repositories
Debug Mode

Enable debug mode by adding to your configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token",
        "DEBUG": "mcp:*"
      }
    }
  }
}
Security Best Practices
  1. Never commit tokens to version control
  2. Use environment variables for sensitive data
  3. Limit token permissions to minimum required scopes
  4. Regularly rotate API tokens
  5. Monitor usage of your API tokens
Resources
Official Documentation
MCP Servers Repository
Community Resources
Contributing

Found an issue or want to improve this guide? Please:

  1. Fork this repository
  2. Create a feature branch
  3. Submit a pull request
License

This guide is provided under the MIT License. Feel free to use, modify, and distribute.

Happy coding with MCP and Claude Desktop! 🚀

For questions or support, please open an issue in this repository.

作者情報
resblok
resblok
GitHub

1

フォロワー

8

リポジトリ

0

Gist

1

貢献数

トップ貢献者

oyeakhilloyeakhill
1
タグ
DatabaseAPIFile SystemEmailAutomationAI/LLMAuthentication
スレッド