Railway MCP server

The Railway MCP Server provides a convenient way to manage Railway.app infrastructure through natural language commands. It allows you to deploy services, manage variables, and monitor deployments by connecting Claude and other MCP clients to your Railway account.

Installation Requirements

Prerequisites

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

Installation Methods

Installing via Smithery (Recommended)

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 Cursor settings and find the MCP section
2. Click 'Add new MCP server'
3. Name it (e.g., railway-mcp)
4. Paste this command, replacing <RAILWAY_API_TOKEN> with your token:

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:

"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 within Claude using:

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 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
• service-restart - Restart a service
• service-update - Update service configuration

Deployments

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

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
• variable-copy - Copy variables between environments

Databases

• database-list-types - List available database types
• database-deploy - Deploy a new database service

Example Workflows

Setting up a new service

1. List projects to get the project ID:

Please list all my Railway projects

2. Create a new service from a repository:

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

3. Add environment variables:

Set the variable DATABASE_URL to postgresql://user:pass@host:5432/db for service [service-id] in project [project-id]

4. View the service deployment:

Show me the deployment status for service [service-id]

Troubleshooting

Token Authentication Issues

• Ensure your API token is valid with proper permissions
• Check that the token is correctly formatted in the config file
• Try using the configure tool directly if the environment token isn't working

Server Connection Issues

• Install the latest version of the server
• Verify Node.js version 18+ is installed
• Restart your MCP client after configuration changes

API Errors

• Verify correct project, environment, and service IDs
• Check Railway's status page for service disruptions
• Be mindful of API rate limits

Recommended Combinations

This server works best with MCP clients that have terminal or Git access (like Cursor, Windsurf). Recommended companion MCP servers:

• Git
• GitHub

Client-Specific Notes

For Claude:

• Best for spinning up and monitoring services
• Limited by lack of terminal access

For Cursor:

• Use with GitHub MCP or have repositories already set up
• Always verify changes are pushed to GitHub

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.