Railway MCP server

Railway MCP Server provides a powerful way to manage your Railway.app infrastructure through natural language interactions with Claude and other MCP clients. You can deploy services, manage variables, and monitor deployments without leaving your preferred AI assistant.

Installation

Prerequisites

• Node.js 18+ (for built-in fetch API support)
• An active Railway account
• A Railway API token (create one at https://railway.app/account/tokens)

Installing via Smithery

The recommended installation method is using Smithery:

For Claude Desktop:

npx -y @smithery/cli install @jason-tan-swe/railway-mcp --client claude

For Cursor:

npx -y @smithery/cli@latest run @jason-tan-swe/railway-mcp --config "{\"railwayApiToken\":\"token\"}"

Manual Installation for Cursor

1. Go to your cursor settings and find the MCP section
2. Click 'Add new MCP server'
3. Name it railway-mcp (recommended for clarity)
4. Paste this command into the 'Command' section:

npx -y @jasontanswe/railway-mcp <RAILWAY_API_TOKEN>

Manual Installation for Claude

1. Create or edit your Claude for Desktop config file:

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

2. Add the railway-mcp server to your configuration:

{
  "mcpServers": {
    "railway": {
      "command": "npx",
      "args": ["-y", "@jasontanswe/railway-mcp"],
      "env": {
        "RAILWAY_API_TOKEN": "your-railway-api-token-here"
      }
    }
  }
}

3. Restart Claude for Desktop

4. Alternatively, configure your token directly in Claude:

Please configure the Railway API with my token: {YOUR_API_TOKEN_HERE}

Usage

Available Tools

Authentication

• configure - Set your Railway API token

Projects

• project-list - List all projects in your account
• project-info - Get detailed information about a specific project
• project-create - Create a new project with optional team ID
• project-delete - Delete a project
• project-environments - List all environments in a project

Services

• service-list - List all services in a specific project
• service-info - Get detailed information about a specific service
• service-create-from-repo - Create a new service from a GitHub repository
• service-create-from-image - Create a new service from a Docker image
• service-delete - Delete a service from a project
• service-restart - Restart a service in a specific environment
• service-update - Update service configuration

Deployments

• deployment-list - List recent deployments for a service
• deployment-trigger - Trigger a new deployment for a service
• deployment-logs - Get logs for a specific deployment
• deployment-health-check - Check the health/status of a deployment

Variables

• variable-list - List variables for a service or environment
• variable-set - Create or update a variable
• variable-delete - Delete a variable
• variable-bulk-set - Bulk update variables for a service
• variable-copy - Copy variables between environments

Databases

• database-list-types - List all available database types that can be deployed
• database-deploy - Deploy a new database service

Example Workflow: Setting up a new service

1. List your projects to get the project ID:

   Please list all my Railway projects
   

2. Create a new service from a GitHub repository:

   Please create a new service from my GitHub repository https://github.com/username/repo in project [project-id]
   

3. Set environment variables for the service:

   Please set the PORT variable to 3000 for service [service-id] in project [project-id]
   

4. Trigger a deployment:

   Please trigger a deployment for service [service-id] in project [project-id]
   

Example Workflow: Managing variables

1. List variables for a service:

   Please list all variables for service [service-id] in project [project-id]
   

2. Update a variable:

   Please update the DATABASE_URL variable to "new-connection-string" for service [service-id]
   

3. Delete a variable:

   Please delete the OLD_API_KEY variable from service [service-id]
   

Troubleshooting

Token Authentication Issues

• Ensure your API token is valid and has the necessary permissions
• If using the environment variable method, check that the token is correctly formatted in the config file
• Try using the configure tool directly in Claude if the environment token isn't working

Server Connection Issues

• Check that you've installed the latest version of the server
• Verify that Node.js version 18 or higher is installed
• Restart Claude for Desktop after making changes to the configuration

API Errors

• Verify that you're using correct project, environment, and service IDs
• Check Railway's status page for any service disruptions
• Railway API has rate limits - avoid making too many requests in a short period

Recommendations

• This server works best with MCP clients that have terminal access or Git integration (Cursor, Windsurf)
• For Claude, which lacks terminal access, focus on service monitoring and management rather than deployments
• When using Cursor, always verify changes are pushed to GitHub before deployment with: "Have you pushed our changes to GitHub yet?"
• Consider using this MCP server alongside Git and GitHub MCP servers for a more complete workflow

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "railway" '{"command":"npx","args":["-y","@jasontanswe/railway-mcp"],"env":{"RAILWAY_API_TOKEN":"your-railway-api-token-here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "railway": {
            "command": "npx",
            "args": [
                "-y",
                "@jasontanswe/railway-mcp"
            ],
            "env": {
                "RAILWAY_API_TOKEN": "your-railway-api-token-here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your 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

2. Add this to your configuration file:

{
    "mcpServers": {
        "railway": {
            "command": "npx",
            "args": [
                "-y",
                "@jasontanswe/railway-mcp"
            ],
            "env": {
                "RAILWAY_API_TOKEN": "your-railway-api-token-here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect