npm package: @prmpter/mcp-assistant
Description: Run MCP Assistant over SSE or visa versa
Author: Prmpter
Latest version: 0.0.3

# MCP Assistant

A powerful proxy tool that enables you to run multiple **MCP (Model Context Protocol) servers** simultaneously and expose them through a unified SSE (Server-Sent Events) endpoint. MCP Assistant acts as a central gateway, allowing MCP clients and other tools to connect to multiple remote MCP servers through a single, streamlined interface.

## 🚀 Features

- **Multi-Server Support**: Run multiple MCP servers concurrently
- **Unified Interface**: Single SSE endpoint for all connected servers
- **Flexible Server Types**: Support for both stdio-based and SSE-based MCP servers
- **Easy Configuration**: Simple JSON-based configuration
- **Environment Management**: Per-server environment variable support
- **Zero Installation**: Run directly with npx

## 📦 Installation & Usage

### Quick Start

Run MCP Assistant directly using npx (no installation required):

```bash
npx @prmpter/mcp-assistant@latest --config path/to/config.json
```

### Command Line Options

```bash
npx @prmpter/mcp-assistant@latest [options]

Options:
  --config <path>    Path to configuration file (required)
  --help            Show help information
  --version         Show version number
```

## ⚙️ Configuration

### Configuration File Structure

Create a `config.json` file to define your MCP servers:

```json
{
  "mcpServers": {
    "server-name": {
      // Server configuration options
    }
  }
}
```

### Server Types

#### 1. Stdio-based Servers

For servers that communicate via standard input/output:

```json
{
  "server-name": {
    "command": "command-to-run",
    "args": ["arg1", "arg2"],
    "env": {
      "ENV_VAR": "value"
    }
  }
}
```

#### 2. SSE-based Servers

For servers that expose an SSE endpoint:

```json
{
  "server-name": {
    "url": "https://example.com/sse-endpoint"
  }
}
```

### Complete Configuration Example

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "<your_notion_token_here>"
      }
    },
    "gmail": {
      "url": "https://mcp.composio.dev/gmail/xxxx"
    },
    "youtube-subtitle-downloader": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/mcp-youtube/src/index.ts"
      ]
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    },
    "iterm-mcp": {
      "command": "npx",
      "args": ["-y", "iterm-mcp"]
    }
  }
}
```

## 📋 Configuration Reference

### Server Configuration Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `command` | string | Yes (stdio) | Command to execute for stdio-based servers |
| `args` | string[] | No | Command line arguments |
| `env` | object | No | Environment variables for the server |
| `url` | string | Yes (SSE) | SSE endpoint URL for SSE-based servers |

### Environment Variables

- Set environment variables in the `env` object for stdio-based servers
- Environment variables are isolated per server
- Common variables include API tokens, configuration paths, etc.

## 🔧 Usage Examples

### Basic Usage

1. Create your configuration file:
   ```bash
   touch mcp-config.json
   ```

2. Add your server configurations to the file

3. Run MCP Assistant:
   ```bash
   npx @prmpter/mcp-assistant@latest --config mcp-config.json
   ```

### Development Setup

For development with local MCP servers:

```json
{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["./local-mcp-server/index.js"],
      "env": {
        "DEBUG": "true",
        "LOG_LEVEL": "verbose"
      }
    }
  }
}
```

## 🛠️ Troubleshooting

### Common Issues

1. **Server fails to start**: Check that the command and arguments are correct
2. **Environment variables not working**: Ensure they're properly quoted in JSON
3. **Connection issues**: Verify SSE URLs are accessible and properly formatted

### Debug Mode

Enable verbose logging by setting environment variables:

```bash
DEBUG=mcp-assistant:* npx @prmpter/mcp-assistant@latest --config config.json
```

## 📖 How It Works

MCP Assistant acts as a proxy layer that:

1. **Reads Configuration**: Parses your configuration file to identify servers
2. **Starts Servers**: Launches stdio-based servers and connects to SSE-based servers
3. **Manages Communication**: Routes messages between clients and appropriate servers
4. **Provides Unified Interface**: Exposes all servers through a single SSE endpoint

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## 📄 License

See the [LICENSE](LICENSE) file for details.

---

*Built for the Model Context Protocol ecosystem*