Skip to content
ByteMCP

Local Deployment (stdio)

The stdio mode is the default deployment method for local MCP clients like Claude Desktop.

How stdio Mode Works

Section titled “How stdio Mode Works”

In stdio mode, ByteMCP communicates via standard input/output:

AI Assistant ←→ stdin/stdout ←→ ByteMCP ←→ Database

The AI assistant spawns ByteMCP as a subprocess and exchanges JSON-RPC messages.

Setup

Section titled “Setup”

1. Build the Project

Section titled “1. Build the Project”
Terminal window
cd byte-mcp
npm install
npm run build

2. Configure Environment

Section titled “2. Configure Environment”

Create .env with database credentials:

DB_HOST=localhost
DB_DATABASE=bytefederal
DB_USER=your_user
DB_PASSWORD=your_password
MCP_MODE=stdio

3. Test Manually

Section titled “3. Test Manually”
Terminal window
npm start

The server will wait for JSON-RPC input on stdin.

Claude Desktop Integration

Section titled “Claude Desktop Integration”

Configuration File Location

Section titled “Configuration File Location”

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Configuration

Section titled “Configuration”
{
  "mcpServers": {
    "bytefederal-atm": {
      "command": "node",
      "args": ["/absolute/path/to/byte-mcp/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "bytefederal",
        "DB_USER": "your_user",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Important Notes

Section titled “Important Notes”
  • Use absolute paths for the args array
  • Environment variables are passed directly to the subprocess
  • Restart Claude Desktop after configuration changes

Development Mode

Section titled “Development Mode”

For development with hot reload:

Terminal window
npm run dev

This uses tsx watch to automatically rebuild on changes.

Testing the Connection

Section titled “Testing the Connection”

Verify in Claude Desktop

Section titled “Verify in Claude Desktop”
  1. Open Claude Desktop
  2. Look for the MCP tools indicator
  3. Click to expand available tools
  4. You should see 4 ByteMCP tools

Test Query

Section titled “Test Query”

Try asking Claude:

“Find Bitcoin ATMs near Miami, FL”

Claude should invoke the find_nearest_bitcoin_atm tool and return results.

Troubleshooting

Section titled “Troubleshooting”

”Server not found”

Section titled “”Server not found””
  • Check the path in args is absolute and correct
  • Verify the project is built (dist/index.js exists)
  • Check file permissions

”Database connection failed”

Section titled “”Database connection failed””
  • Verify database credentials in env
  • Test MySQL connection manually:
    Terminal window
    mysql -h localhost -u your_user -p your_database

No tools appearing

Section titled “No tools appearing”
  • Restart Claude Desktop completely
  • Check Claude Desktop logs for errors
  • Verify JSON syntax in config file

Security Considerations

Section titled “Security Considerations”
  • Database credentials are stored in the Claude config file
  • The config file should have restricted permissions
  • Consider using a read-only database user

Next Steps

Section titled “Next Steps”