Railway-Account-mcp-server by ARJ999 - MCP Server

Railway Account MCP Server

Remote MCP Server for Managing Railway Projects via HTTP/SSE Transport

A production-ready Model Context Protocol (MCP) server that enables comprehensive Railway infrastructure management through HTTP/SSE transport. This server can be deployed to Railway and accessed remotely by any MCP-compatible client.

🌟 Overview

The Railway Account MCP Server provides a remote-accessible interface for managing Railway projects, services, environments, and deployments. Unlike traditional STDIO-based MCP servers that run locally, this server uses HTTP/SSE (Server-Sent Events) transport, allowing it to be deployed to Railway and accessed from anywhere.

Key Features

✅ Remote Access: Deploy once, access from multiple clients
✅ HTTP/SSE Transport: Standard web protocols for broad compatibility
✅ 14 Railway Tools: Complete Railway management capabilities
✅ Railway-Ready: Optimized for Railway deployment with Dockerfile
✅ CORS Enabled: Works with web-based MCP clients
✅ Health Monitoring: Built-in health check endpoint
✅ Production-Ready: Comprehensive error handling and logging

[!IMPORTANT] The MCP server doesn't include destructive actions by design, but you should still monitor which tools and commands are being executed.

🚀 Quick Start

Prerequisites

Railway Account: Sign up at railway.app
Railway CLI: Install via npm install -g @railway/cli
Railway Token: Generate from Railway dashboard

Deploy to Railway

Option 1: Deploy from GitHub (Recommended)

Fork or Clone this Repository

git clone https://github.com/ARJ999/Railway-Account-mcp-server.git
cd Railway-Account-mcp-server

Login to Railway
```
railway login
```
Create a New Project
```
railway init
```

Set Environment Variables

railway variables set RAILWAY_TOKEN=your_railway_token_here

Deploy
```
railway up
```
Generate Domain
```
railway domain
```
Get Your Deployment URL
```
railway status
```

Option 2: Deploy via Railway Dashboard

Go to railway.app/new
Select "Deploy from GitHub repo"
Choose ARJ999/Railway-Account-mcp-server
Add environment variable: RAILWAY_TOKEN with your Railway API token
Deploy and wait for the build to complete
Go to Settings → Networking → Generate Domain
Copy your public domain URL

🔧 Configuration

Environment Variables

Variable	Required	Description
`RAILWAY_TOKEN`	Yes	Railway API token for authentication
`PORT`	No	Server port (default: 3000, Railway auto-assigns)

Getting Your Railway Token

Go to railway.app/account/tokens
Click "Create Token"
Give it a descriptive name (e.g., "MCP Server")
Copy the generated token
Add it as an environment variable in your Railway project

📡 API Endpoints

Once deployed, your server exposes the following endpoints:

Endpoint	Method	Description
`/health`	GET	Health check and server status
`/sse`	GET	SSE endpoint for MCP communication
`/message`	POST	Message endpoint for client requests

Example URLs

If your Railway domain is railway-account-mcp-server-production.up.railway.app:

Health Check: https://railway-account-mcp-server-production.up.railway.app/health
SSE Endpoint: https://railway-account-mcp-server-production.up.railway.app/sse
Message Endpoint: https://railway-account-mcp-server-production.up.railway.app/message

🔌 Connecting MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "railway-account": {
      "transport": {
        "type": "sse",
        "url": "https://your-railway-domain.up.railway.app/sse"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "railway-account": {
      "transport": {
        "type": "sse",
        "url": "https://your-railway-domain.up.railway.app/sse"
      }
    }
  }
}

VS Code (with MCP Extension)

Add to .vscode/mcp.json:

{
  "servers": {
    "railway-account": {
      "type": "sse",
      "url": "https://your-railway-domain.up.railway.app/sse"
    }
  }
}

Generic MCP Client

For any MCP client that supports SSE transport:

{
  "transport": {
    "type": "sse",
    "url": "https://your-railway-domain.up.railway.app/sse"
  }
}

🛠️ Available Tools

The server provides 14 comprehensive Railway management tools:

System Status

check-railway-status - Verify Railway CLI installation and authentication

Project Management

list-projects - List all Railway projects in your account
create-project-and-link - Create a new Railway project

Service Management

list-services - List all services in a project
link-service - Link to a specific service
deploy - Deploy a service to Railway
deploy-template - Deploy from Railway template library

Environment Management

create-environment - Create a new environment
link-environment - Link to a specific environment

Configuration & Variables

list-variables - List environment variables
set-variables - Set environment variables
generate-domain - Generate a railway.app domain

Monitoring & Deployment

list-deployments - List all deployments
get-logs - Retrieve build or deployment logs

📖 Usage Examples

Example 1: Create and Deploy a New Project

User: "Create a new Railway project called 'my-api' and deploy it"

AI Workflow:

Uses create-project-and-link to create the project
Uses deploy to deploy the service
Uses generate-domain to create a public URL
Reports the deployment URL

Example 2: Manage Environment Variables

User: "Set DATABASE_URL for my backend service"

AI Workflow:

Uses list-services to find services
Uses link-service to target the backend
Uses set-variables to set DATABASE_URL
Uses list-variables to confirm

Example 3: Monitor Deployments

User: "Show me the logs for my latest deployment"

AI Workflow:

Uses list-deployments to find recent deployments
Uses get-logs to retrieve logs
Displays formatted log output

🏗️ Architecture

Technology Stack

Protocol: Model Context Protocol (MCP) 1.0
Transport: HTTP/SSE (Server-Sent Events)
Framework: Express.js
Language: TypeScript/Node.js
SDK: @modelcontextprotocol/sdk v1.17.1+
CLI Integration: Railway CLI wrapper
API: GraphQL client for Railway API
Validation: Zod schema validation

Component Architecture

┌─────────────────────────────────────┐
│         MCP Client                  │
│  (Claude/Cursor/VS Code/etc.)       │
└──────────────┬──────────────────────┘
               │ HTTP/SSE
               ▼
┌──────────────────────────────────────┐
│     Railway Account MCP Server       │
│     (Deployed on Railway)            │
│                                      │
│  ┌────────────────────────────────┐ │
│  │  Express.js HTTP Server        │ │
│  │  - CORS enabled                │ │
│  │  - Health check endpoint       │ │
│  │  - SSE transport               │ │
│  └─────────────┬──────────────────┘ │
│                │                     │
│  ┌─────────────▼──────────────────┐ │
│  │  14 MCP Tools                  │ │
│  │  - Project Management          │ │
│  │  - Service Management          │ │
│  │  - Environment Management      │ │
│  │  - Variables & Config          │ │
│  │  - Monitoring & Logs           │ │
│  └─────────────┬──────────────────┘ │
│                │                     │
│  ┌─────────────▼──────────────────┐ │
│  │  Railway CLI Wrapper           │ │
│  └─────────────┬──────────────────┘ │
│                │                     │
│  ┌─────────────▼──────────────────┐ │
│  │  GraphQL API Client            │ │
│  └────────────────────────────────┘ │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│         Railway API                  │
└──────────────────────────────────────┘

🔒 Security

Built-in Safety Features

✅ No Destructive Operations: Excludes delete/destroy commands by design
✅ Token-Based Authentication: Uses Railway API tokens
✅ CORS Protection: Configurable CORS headers
✅ Environment Isolation: Each deployment has isolated environment
✅ Secure Token Storage: Railway tokens stored as environment variables

Best Practices

Protect Your Railway Token: Never commit tokens to version control
Use Environment Variables: Always use Railway's environment variable system
Monitor Access: Review Railway dashboard regularly
Rotate Tokens: Periodically regenerate Railway API tokens
Limit Permissions: Use tokens with minimum required permissions

🧪 Testing

Test Health Endpoint

curl https://your-railway-domain.up.railway.app/health

Expected response:

{
  "status": "healthy",
  "service": "Railway Account MCP Server",
  "version": "1.0.0",
  "timestamp": "2025-10-12T12:00:00.000Z"
}

Test SSE Connection

curl -N https://your-railway-domain.up.railway.app/sse

You should see SSE events streaming.

🐛 Troubleshooting

Issue: "Railway CLI not found"

Solution: The Railway CLI is installed in the Docker container. Ensure your Dockerfile includes:

RUN npm install -g @railway/cli

Issue: "Not authenticated with Railway"

Solution: Ensure you've set the RAILWAY_TOKEN environment variable in your Railway project.

Issue: "CORS errors in browser"

Solution: The server includes CORS headers. If you need to restrict origins, modify the CORS configuration in src/index.ts.

Issue: "Connection timeout"

Solution:

Check if your Railway service is running: railway status
Verify your domain is correctly configured
Check Railway logs: railway logs

📚 Development

Local Development

Clone the repository

git clone https://github.com/ARJ999/Railway-Account-mcp-server.git
cd Railway-Account-mcp-server

Install dependencies
```
pnpm install
```

Set environment variables

export RAILWAY_TOKEN=your_token_here
export PORT=3000

Run in development mode
```
pnpm dev
```
Build for production
```
pnpm build
```
Start production server
```
pnpm start
```

Testing

# Run tests
pnpm test

# Run tests once
pnpm test:run

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Formatting
pnpm format

📄 License

MIT License - see file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

GitHub Issues: Report bugs or request features
Railway Documentation: docs.railway.com
MCP Specification: modelcontextprotocol.io

🙏 Acknowledgments

Based on the official Railway MCP Server by the Railway team.

Original Repository: railwayapp/railway-mcp-server
Railway: railway.app
Model Context Protocol: Anthropic

Author: ARJ999
Version: 1.0.0
Last Updated: October 12, 2025