Railway MCP Server

Instructions

Implementation Reference

• src/tools/deploy.ts:28-63 (handler)

  The handler function for the 'deploy' MCP tool. It invokes deployRailwayProject from the CLI module, handles success/error responses, and formats the output using createToolResponse.

  handler: async ({
  	workspacePath,
  	ci,
  	environment,
  	service,
  }: DeployOptions) => {
  	const {
  		workspacePath: wsPath,
  		ci: ciMode = false,
  		environment: env,
  		service: svc,
  	} = { workspacePath, ci, environment, service };
  	try {
  		const result = await deployRailwayProject({
  			workspacePath: wsPath,
  			ci: ciMode,
  			environment: env,
  			service: svc,
  		});
  		return createToolResponse(
  			`✅ Successfully triggered a deployment for Railway project. This process will take some time to complete:\n\n${result}`,
  		);
  	} catch (error: unknown) {
  		const errorMessage =
  			error instanceof Error ? error.message : "Unknown error occurred";
  		return createToolResponse(
  			"❌ Failed to deploy Railway project\n\n" +
  				`**Error:** ${errorMessage}\n\n` +
  				"**Next Steps:**\n" +
  				"• Ensure you have a Railway project linked\n" +
  				"• Check that the environment and service exist\n" +
  				"• Verify your project has the necessary files for deployment\n" +
  				"• Check that you have permissions to deploy to this project",
  		);
  	}
  },

• src/tools/deploy.ts:11-27 (schema)

  Zod schema defining the input parameters for the 'deploy' tool: workspacePath (required), ci, environment, service (optional).

  inputSchema: {
  	workspacePath: z.string().describe("The path to the workspace to deploy"),
  	ci: z
  		.boolean()
  		.optional()
  		.describe(
  			"Stream build logs only, then exit (equivalent to setting $CI=true)",
  		),
  	environment: z
  		.string()
  		.optional()
  		.describe("Environment to deploy to (defaults to linked environment)"),
  	service: z
  		.string()
  		.optional()
  		.describe("Service to deploy to (defaults to linked service)"),
  },

• src/index.ts:21-31 (registration)

  Main MCP server registration loop that dynamically registers all tools (including 'deploy') from the tools module by name, schema, and handler.

  Object.values(tools).forEach((tool) => {
  	server.registerTool(
  		tool.name,
  		{
  			title: tool.title,
  			description: tool.description,
  			inputSchema: tool.inputSchema,
  		},
  		tool.handler,
  	);
  });

• src/tools/index.ts:4-4 (registration)

  Re-export of the deployTool from its implementation file, making it available for import in the main server.

  export { deployTool } from "./deploy";

• src/cli/deployment.ts:14-76 (helper)

  Core helper function deployRailwayProject that executes the 'railway up' CLI command with options, handles service linking, and error analysis. Called by the deploy tool handler.

  export const deployRailwayProject = async ({
    workspacePath,
    environment,
    service,
    ci,
  }: DeployOptions): Promise<string> => {
    try {
      await checkRailwayCliStatus();
      const result = await getLinkedProjectInfo({ workspacePath });
      if (!result.success) {
        throw new Error(result.error);
      }
  
      // Build the railway up command with options
      let command = "railway up";
  
      if (ci) {
        command += " --ci";
      }
  
      if (environment) {
        command += ` --environment ${environment}`;
      }
  
      if (service) {
        command += ` --service ${service}`;
      }
  
      const { output: deployOutput } = await runRailwayCommand(
        command,
        workspacePath
      );
  
      // After deployment, try to link a service if none is linked
      try {
        // Check if there are any services available
        const servicesResult = await getRailwayServices({ workspacePath });
        if (
          servicesResult.success &&
          servicesResult.services &&
          servicesResult.services.length > 0
        ) {
          // Link the first available service
          const firstService = servicesResult.services[0];
          const { output: linkOutput } = await runRailwayCommand(
            `railway service ${firstService}`,
            workspacePath
          );
          return `${deployOutput}\n\nService linked: ${firstService}\n${linkOutput}`;
        }
      } catch (linkError) {
        // If linking fails, just return the deployment output
        console.warn(
          "Warning: Could not automatically link service after deployment:",
          linkError
        );
      }
  
      return deployOutput;
    } catch (error: unknown) {
      return analyzeRailwayError(error, "railway up");
    }
  };