Simple MCP Character Counter

A minimal Model Context Protocol (MCP) server for teaching purposes. This server provides a single tool that counts the number of characters in a word or phrase.

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI assistants (like Claude) to interact with external tools and data sources. This simple example demonstrates the core concepts of building an MCP server.

Features

This teaching example includes:

• One simple tool: count_characters - counts characters in text
• Clear documentation: Every function and concept is explained
• Minimal dependencies: Only requires the MCP Python SDK

Setup

1. Install Dependencies

python3 -m venv venv
source venv/bin/activate

Or install directly:

python -m pip install -r requirements.txt

2. Test the Server

You can run the server directly to make sure it works:

python server.py

The server will start and wait for input via stdin. You can press Ctrl+C to stop it.

Usage with Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to Claude's configuration file.

python server.py

The server will start and wait for input via stdin. You can press Ctrl+C to stop it.

Usage with Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to Claude's configuration file.

Quick Configuration

A ready-to-use configuration file is included: claude_desktop_config.json

Option 1: Copy the entire config (if you have no other MCP servers)

# MacOS
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows (PowerShell)
Copy-Item claude_desktop_config.json $env:APPDATA\Claude\claude_desktop_config.json

Option 2: Merge with existing config (if you have other MCP servers)

1. Open your Claude Desktop configuration file:

   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the simple-character-counter entry to your existing mcpServers section:

{
  "mcpServers": {
    "simple-character-counter": {
      "command": "python",
      "args": ["/Users/electron/workspace/Nanocentury AI/NIO-MCPs/supersimpleMCP/server.py"]
    }
  }
}

Note: Update the path in args if you move this folder to a different location.

3. Restart Claude Desktop

4. The tool will now be available! You can ask Claude to:

   • "Count the characters in 'hello'"
   • "How many characters are in 'MCP is awesome'?"
   • "Use the character counter on this text: ..."

How It Works

Server Structure

The server has three main parts:

1. Server Instance (app = Server(...)): Creates the MCP server
2. Tool Definition (@app.list_tools()): Describes what tools are available
3. Tool Handler (@app.call_tool()): Executes tools when called

The Character Counter Tool

When you ask Claude to count characters:

1. Claude sees the count_characters tool is available
2. Claude calls the tool with your text
3. The server counts the characters using len(text)
4. The server returns a formatted response
5. Claude shares the result with you

Code Walkthrough

Key Components

# Create the server
app = Server("simple-character-counter")

# Define available tools
@app.list_tools()
async def list_tools() -> list[Tool]:
    return [Tool(...)]

# Handle tool execution
@app.call_tool()
async def call_tool(name: str, arguments: Any) -> list[TextContent]:
    # Your tool logic here
    pass

# Start the server
async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, ...)

Learning Points

This example teaches:

1. MCP Server Basics: How to create and run an MCP server
2. Tool Definition: How to define a tool with name, description, and input schema
3. Tool Execution: How to handle tool calls and return results
4. JSON Schema: How to specify input parameters for tools
5. Async Python: Basic async/await patterns used in MCP

Extending This Example

Try modifying this server to practice:

• Add a new tool (e.g., count_words, reverse_text)
• Add more parameters to the existing tool
• Return different formats of output
• Add error handling for edge cases

Troubleshooting

Server won't start in Claude Desktop:

• Check that the full path to server.py is correct
• Make sure you've installed the requirements
• Restart Claude Desktop after config changes

Tool doesn't appear:

• Verify the JSON configuration is valid (no syntax errors)
• Check Claude's developer logs for error messages

Resources

• MCP Documentation
• MCP Python SDK

License

This is a teaching example - feel free to use and modify as needed!