npm package: @opichi/server-railway
Description: MCP server for Railway CLI integration
Author: MCP Tools
Latest version: 1.0.2

# Railway MCP Server

A Model Context Protocol (MCP) server that provides a standardized interface for Large Language Models (LLMs) to interact with the Railway Command Line Interface (CLI).

## Features

- **Complete Railway CLI Integration**: Supports all Railway CLI commands as MCP tools
- **Authentication Management**: Handles Railway login/logout and user authentication
- **State Management**: Maintains project and environment context
- **Error Handling**: Provides structured error messages and clear feedback
- **Easy Installation**: Available as an NPM package, runnable via npx

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- Railway CLI installed and available in your system's PATH

### Install Railway CLI

```bash
# Install Railway CLI if not already installed
npm install -g @railway/cli
```

### Install MCP Server

```bash
# Run directly with npx (recommended)
npx @opichi/server-railway

# Or install globally
npm install -g @opichi/server-railway
```

## Configuration

### VS Code with MCP Extension

Add the following to your VS Code `settings.json`:

```json
{
  "mcpServers": {
    "railway": {
      "command": "npx",
      "args": [
        "-y",
        "@opichi/server-railway"
      ],
      "disabled": false
    }
  }
}
```

### Cursor IDE

Add to your Cursor configuration:

```json
{
  "mcpServers": {
    "railway": {
      "command": "npx",
      "args": [
        "-y",
        "@opichi/server-railway"
      ]
    }
  }
}
```

## Supported Commands

### Core Management
- `railway_login` - Authenticate with Railway
- `railway_logout` - Log out of Railway account
- `railway_whoami` - Display current user info
- `railway_list` - List all Railway projects
- `railway_link` - Connect directory to Railway project
- `railway_unlink` - Disconnect from Railway project
- `railway_init` - Create new Railway project
- `railway_delete` - Delete a project
- `railway_docs` - Open Railway documentation
- `railway_version` - Get Railway CLI version
- `railway_help` - Get help for specific commands

### Deployment & Services
- `railway_up` - Deploy code to Railway
- `railway_down` - Remove recent deployment
- `railway_logs` - Show deployment logs
- `railway_add` - Add plugin to project
- `railway_connect` - Connect to database shell
- `railway_domain` - Manage custom domains
- `railway_deploy` - Deploy template to project

### Environment & Variables
- `railway_environment` - Manage environments
- `railway_variables` - Work with environment variables

### Local Development
- `railway_run` - Run command with Railway variables
- `railway_shell` - Open shell with Railway variables
- `railway_status` - View project status
- `railway_open` - Open project in Railway dashboard
- `railway_completion` - Generate shell completion scripts

## Usage Example

Once configured in your MCP-compatible client, you can use natural language to interact with Railway:

```
"Login to Railway and show me my projects"
"Create a new Railway project called 'my-app'"
"Deploy the current directory to Railway"
"Show me the logs for my latest deployment"
"Set the environment variable DATABASE_URL to my production database"
```

## Error Handling

The server provides clear error messages when:
- Railway CLI is not installed or not found in PATH
- Authentication is required but user is not logged in
- Commands fail due to invalid arguments or Railway API issues
- Network connectivity problems

## Development

### Setup

```bash
git clone <repository-url>
cd railway-mcp-server
npm install
```

### Build

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Testing

```bash
npm test
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Check the [Railway CLI documentation](https://docs.railway.app/reference/cli-api)
- Open an issue on GitHub
- Review the MCP specification at [Model Context Protocol](https://modelcontextprotocol.io/)