MCP Server 101

🚀 MCP Server Setup Documentation

This guide provides detailed instructions for setting up a Model Control Protocol (MCP) server integrated with Claude Desktop. The MCP server extends Claude's capabilities by allowing it to interact with external systems and APIs, including AWS services and GitHub.

🚀 Quick Start

Prerequisites

• Install Python 3.8+
• Install the Claude Desktop application
• Install the uv package manager
• Have a basic understanding of Python and command-line operations

📦 Installation

1. Install Required Packages

Run the following command to install the required packages using uv:

uv add MCP --platforms linux/x86_64,linux/arm64,osx/x86_64,osx/arm64,win/x86_64,win/arm64

2. Create an MCP Configuration File

Create the ~/.config/mcp/config.json file and add the following content:

{
    "version": "1.0",
    "servers": {
        "local": {
            "host": "localhost",
            "port": 5005,
            "type": "grpc"
        }
    },
    "apis": {
        "aws": {
            "region": "us-east-2",
            "access_key_id": "YOUR_ACCESS_KEY_ID",
            "secret_access_key": "YOUR_SECRET_ACCESS_KEY"
        },
        "github": {
            "token": "YOUR_GITHUB_TOKEN"
        }
    }
}

3. Start the MCP Server

Run the following command in the terminal to start the MCP server:

uv run MCP --server local

Test the Server

Verify that the MCP server is running properly:

curl http://localhost:5005/ping

Expected output:

{
    "status": "success",
    "message": "MCP server is running"
}

Configure Claude Desktop

1. Open Settings

In Claude Desktop, navigate to Edit > Settings.

2. Add an MCP Server

Under the Services tab, click Add Service and enter the following information:

• Name: MCP Server
• Type: Custom
• URL: http://localhost:5005

3. Apply Settings

Click Add to complete the configuration.

🔧 Technical Details

Advanced Configuration

Environment Variables

Run the following command in the terminal to set environment variables:

export MCP_API_KEY="your_api_key"

Custom Dependencies

Edit the ~/.config/mcp/config.json file and add custom dependencies:

{
    "dependencies": {
        "custom-package": "^1.0.0"
    }
}

Run the following command to install the dependencies:

uv run MCP --install

Error Handling

View the error logs in the ~/.config/mcp/errors.log file.

Troubleshooting

Problem: Unable to Connect to the Server

Solution: Check the server status:

curl http://localhost:5005/ping

Ensure that the firewall allows traffic on port 5005.

Problem: Invalid Configuration File

Solution: Verify that the config.json file is in the correct format. Use a JSON validation tool if necessary.

💻 Usage Examples

AWS Integration

import boto3

def list_ec2_instances():
    ec2 = boto3.client('ec2', region_name='us-east-2')
    instances = ec2.describe_instances()
    return instances['Reservations']

GitHub Integration

import os
from github import Github

def get_repository_info(repo):
    g = Github(os.getenv("GITHUB_TOKEN"))
    repo = g.get_repo(repo)
    return repo.raw_data

📚 Documentation

Security Considerations

• Avoid hard - coding sensitive information in the code.
• Use environment variables to store confidential data.
• Consider implementing an authentication mechanism for the MCP server.
• Be aware of the security of functions exposed to the network.

Resources

• MCP Documentation