Simple Model Context Protocol (MCP) Server

A simple MCP server that provides basic utility tools for text manipulation, file operations, and calculations. This server can be connected to Claude AI desktop app to extend its capabilities.

Features

Available Tools:

• echo: Echo back any text you provide
• calculate: Perform basic mathematical calculations
• word_count: Count words, characters, and lines in text
• reverse_text: Reverse any text string
• uppercase: Convert text to uppercase
• list_files: List files and directories
• get_system_info: Get basic system information

Quick Setup

1. Run the setup script:

   ./setup.sh
   

2. Or manual setup:

   # Create virtual environment
   python3 -m venv venv
   source venv/bin/activate
   
   # Install dependencies
   pip install -r requirements.txt
   

Connecting to Claude AI Desktop App

Step 1: Locate Claude Configuration Directory

The configuration file location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Update Claude Configuration

1. Find or create the configuration file at the location above
2. Add the MCP server configuration:

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "/Users/Projects/MCP/venv/bin/python",
      "args": ["/Users/Projects/MCP/server.py"],
      "env": {}
    }
  }
}

Important: Replace /Users/Projects/MCP/server.py with the actual absolute path to your server.py file.

Step 3: Restart Claude Desktop App

Close and restart the Claude desktop application completely.

Step 4: Test the Connection

1. Open Claude desktop app
2. In a new conversation, you should see MCP tools available
3. Try asking Claude to use one of the tools, for example:
   • "Can you calculate 15 * 23 for me?"
   • "Please count the words in this text: 'Hello world this is a test'"
   • "List the files in the current directory"

Testing the Server Manually

You can test the server directly:

# Activate virtual environment
source venv/bin/activate

# Run the server (it will wait for input)
python server.py

The server communicates via stdio (standard input/output) using JSON-RPC protocol.

Troubleshooting

Common Issues:

1. "Import mcp could not be resolved"

   • Make sure you've installed the requirements: pip install -r requirements.txt
   • Activate your virtual environment: source venv/bin/activate

2. Claude doesn't show MCP tools

   • Check that the path in claude_desktop_config.json is absolute and correct
   • Ensure Claude desktop app was completely restarted
   • Check Claude's logs for any error messages

3. Server won't start

   • Ensure Python 3.7+ is installed
   • Check that all dependencies are installed
   • Try running the setup script again

Configuration Example for Different Setups:

If using conda environment:

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "conda",
      "args": ["run", "-n", "your_env_name", "python", "/full/path/to/server.py"],
      "env": {}
    }
  }
}

If using system Python:

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "/usr/bin/python3",
      "args": ["/full/path/to/server.py"],
      "env": {}
    }
  }
}

Extending the Server

To add new tools:

1. Add a new Tool definition in the list_tools() function
2. Add the corresponding handler in the call_tool() function
3. Restart the server and Claude desktop app

Example Usage in Claude

Once connected, you can ask Claude to:

• "Calculate the square root of 144"
• "Count words in this paragraph: [your text]"
• "Convert this text to uppercase: hello world"
• "Show me what files are in my home directory"
• "What's my system information?"

File Structure

MCP/
├── server.py                    # Main MCP server code
├── requirements.txt             # Python dependencies
├── setup.sh                     # Setup script
├── claude_desktop_config.json   # Example Claude config
├── README.md                    # This file
└── venv/                        # Virtual environment (created by setup)

Security Note

This server includes a basic calculate function that uses Python's eval(). In a production environment, you should replace this with a safer mathematical expression parser.

License

This project is provided as-is for educational and development purposes.