Railway MCP Server
Let Claude and other MCP clients manage your Railway.app infrastructure. Deploy services, manage variables, and monitor deployments - all through natural language.
| Please Note: This is under development and not all features are available yet. 🚧 |
|---|
A Model Context Protocol (MCP) server for integrating with the Railway.app platform.
Table of Contents
Features • Installation • Available Tools • Example Workflows • Security • Troubleshooting • Contributing
Features
| Status | Meaning |
|---|---|
| ✅ | Complete |
| 🚧🔨⏳ | Being Built or Needs Testing |
| ❌ | Not Built at the moment |
- ✅ Authentication with Railway API tokens
- ✅ Project management (list, info, delete)
- ✅ Deployment management (list, restart)
- ✅ Service management (create from GitHub repo or Docker image, list)
- ✅ Variable management (list, create/update, delete)
- ✅ Service Network management
- ✅ Volume management
- ❌ Full support for all templates
- 🚧🔨⏳ Database template support
- Automatic database and networking workflows
- 🚧🔨⏳ Most commonly used workflows
- ❌ Automatic GitHub repository linking for services
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)
Quick Start
This MCP server is designed to work with MCP Clients like:
- Claude for Desktop | ✅ Battle-Tested
- Cursor | ✅ Needs Testing
- Cline | 🚧🔨⏳ Needs Testing
- Windsurf | 🚧🔨⏳ Needs Testing
- Other MCP Clients | 🚧🔨⏳ Needs Testing
Installing via Smithery
To install railway-mcp automatically, we recommend using Smithery
Claude Desktop
npx -y @smithery/cli install @jason-tan-swe/railway-mcp --client claude
Cursor
npx -y @smithery/cli@latest run @jason-tan-swe/railway-mcp --config "{\"railwayApiToken\":\"token\"}"
Manual Installation For Cursor
-
Head to your cursor settings and find the MCP section
-
Click 'Add new MCP server'
-
Name it however, you like, we recommend
railway-mcpfor better clarity -
Paste this command into the 'Command' section, where <RAILWAY_API_TOKEN> is your accounts Railway token:
npx -y @jasontanswe/railway-mcp <RAILWAY_API_TOKEN>
Manual Installation For Claude
-
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
- macOS:
-
Add the railway-mcp server to your configuration with your API token:
"railway": {
"command": "npx",
"args": ["-y", "@jasontanswe/railway-mcp"],
"env": {
"RAILWAY_API_TOKEN": "your-railway-api-token-here"
}
}
When you have multiple MCP servers, your config file might look like this:
{
"mcpServers": {
// ... All of your existing MCP servers ...
// Add the railway-mcp server to your configuration with your API token
"railway": {
"command": "npx",
"args": ["-y", "@jasontanswe/railway-mcp"],
"env": {
"RAILWAY_API_TOKEN": "your-railway-api-token-here"
}
}
}
}
-
Restart Claude for Desktop
-
You can now start using Railway tools directly in Claude. For example:
Please list all my Railway projects
- Alternatively, if you don't want to add your token to the configuration file, you can configure it within Claude using:
Please configure the Railway API with my token: {YOUR_API_TOKEN_HERE}
Recommendations and Other Information
This server best combines with MCP-clients that have access to terminal or with Git (Cursor, Windsurf). Using this MCP with others is recommended as railway-mcp orchestrates containers and streamlines your deployment process seamlessly.
Recommended MCP servers to combine with
- Git || Official Link
- GitHub || Official || Smithery
For Claude
- Out of the box, Claude does not have terminal access, so it cannot trigger deployments as it will not be able to get the latest commit.
- Spinning up different services and monitoring them are the best use case with Claude.
For Cursor
- Use with GitHub MCP or have the repository already setup on GitHub and cloned locally on your machine to leverage full integration with railway-mcp.
- When Cursor makes a change, it may forget to push it's changes to GitHub causing it to try and deploy a commit that Railway cannot pull.
- SOLUTION: Always ask or include somewhere in your prompt:
Have you pushed our changes to GitHub yet?
- SOLUTION: Always ask or include somewhere in your prompt:
Security Considerations
- Railway API tokens provide full access to your account. Keep them secure.
- When using the environment variable method, your token is stored in the Claude Desktop configuration file.
- Sensitive variable values are automatically masked when displayed.
- All API calls use HTTPS for secure communication.
- The server's memory-only token storage means your token is never written to disk outside of the configuration file.
Troubleshooting
If you encounter issues:
-
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
configuretool 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
Contributing
We welcome contributions from the community! Please see our Contributing Guidelines for details on how to get started, development guidelines, and debugging information.
Available Tools
View All
Authentication
configure- Set your Railway API token (only needed if not provided in environment variables)
Projects
project-list- List all projects in your accountproject-info- Get detailed information about a specific projectproject-create- Create a new project with optional team IDproject-delete- Delete a projectproject-environments- List all environments in a project
Services
service-list- List all services in a specific projectservice-info- Get detailed information about a specific serviceservice-create-from-repo- Create a new service from a GitHub repositoryservice-create-from-image- Create a new service from a Docker imageservice-delete- Delete a service from a projectservice-restart- Restart a service in a specific environmentservice-update- Update service configuration (build command, start command, etc.) | 🚧 Needs Testing
Deployments
deployment-list- List recent deployments for a servicedeployment-trigger- Trigger a new deployment for a servicedeployment-logs- Get logs for a specific deploymentdeployment-health-check- Check the health/status of a deployment
Variables
variable-list- List variables for a service or environmentvariable-set- Create or update a variablevariable-delete- Delete a variablevariable-bulk-set- Bulk update variables for a service | 🚧 Needs Testingvariable-copy- Copy variables between environments | 🚧 Needs Testing
Databases
database-list-types- List all available database types that can be deployeddatabase-deploy- Deploy a new database service
Example Workflows
Setting up a new service
- List projects to get the project ID
- Create a new service from a template
- Add environment variables
- View the service deployment
Managing environment variables
- List projects to find your project ID
- List variables to see what's currently set
- Create or update variables as needed
- Delete any obsolete variables