Railway MCP Server

Instructions

Implementation Reference

• src/tools/get-logs.ts:63-123 (handler)

  The main handler function for the 'get-logs' tool. It determines whether to fetch build or deploy logs, checks CLI feature support for advanced options like lines and filter, constructs the appropriate CLI call via helper functions, and handles errors with user-friendly messages.

  handler: async ({
    workspacePath,
    logType,
    deploymentId,
    service,
    environment,
    lines,
    filter,
    json,
  }: GetLogsOptions) => {
    try {
      const features = await getCliFeatureSupport();
      const supportsFiltering =
        features.logs.args.lines && features.logs.args.filter;
      let versionWarning = "";
  
      if ((lines !== undefined || filter !== undefined) && !supportsFiltering) {
        versionWarning =
          "⚠️ **Note:** Your Railway CLI version does not support the 'lines' and 'filter' parameters. " +
          "Please upgrade to Railway CLI v4.9.0 or later to use these features. " +
          "Logs will be streamed without filtering.\n\n";
      }
  
      let result: string;
      if (logType === "build") {
        result = await getRailwayBuildLogs({
          workspacePath,
          deploymentId,
          service,
          environment,
          lines,
          filter,
          json,
        });
      } else {
        result = await getRailwayDeployLogs({
          workspacePath,
          deploymentId,
          service,
          environment,
          lines,
          filter,
          json,
        });
      }
  
      return createToolResponse(versionWarning + result);
    } catch (error: unknown) {
      const errorMessage =
        error instanceof Error ? error.message : "Unknown error occurred";
      return createToolResponse(
        `❌ Failed to get Railway ${logType} logs\n\n` +
          `**Error:** ${errorMessage}\n\n` +
          "**Next Steps:**\n" +
          "• Ensure you have a Railway project linked\n" +
          "• Check that the deployment ID is valid (if provided)\n" +
          "• Verify the service and environment exist\n" +
          "• Run `railway link` to ensure proper project connection"
      );
    }
  },

• src/tools/get-logs.ts:19-62 (schema)

  Zod-based input schema defining parameters for the 'get-logs' tool, including workspace path, log type, optional deployment/service/environment IDs, lines, filter, and JSON output flag.

  inputSchema: {
    workspacePath: z
      .string()
      .describe("The path to the workspace to get logs from"),
    logType: z
      .enum(["build", "deploy"])
      .describe(
        "Type of logs to retrieve: 'build' for build logs or 'deploy' for deployment logs"
      ),
    deploymentId: z
      .string()
      .optional()
      .describe(
        "Deployment ID to pull logs from. Omit to pull from latest deployment"
      ),
    service: z
      .string()
      .optional()
      .describe("Service to view logs from (defaults to linked service)"),
    environment: z
      .string()
      .optional()
      .describe(
        "Environment to view logs from (defaults to linked environment)"
      ),
    lines: z
      .number()
      .optional()
      .describe(
        "Number of log lines to return (disables streaming). Requires Railway CLI v4.9.0+. Useful for searching through recent logs."
      ),
    filter: z
      .string()
      .optional()
      .describe(
        "Filter logs by search terms or attributes. Requires Railway CLI v4.9.0+. Examples: 'error', '@level:error', '@level:warn AND rate limit', 'user login', '@status:500'. See https://docs.railway.com/guides/logs for more info."
      ),
    json: z
      .boolean()
      .optional()
      .describe(
        "JSON provides structured log data with more information (e.g. timestamps) but uses more tokens. Defaults to false to save tokens. Set to true for more detailed logs."
      ),
  },

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

  Dynamic registration of all tools (including 'get-logs') with the MCP server by iterating over the tools object imported from './tools' and calling registerTool for each.

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

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

  Export of the getLogsTool object, making it available via barrel export for inclusion in the tools namespace used during MCP server registration.

  export { getLogsTool } from "./get-logs";

• src/cli/logs.ts:95-126 (helper)

  Helper function to execute Railway CLI command for build logs, handling command construction, project linking check, execution, and error analysis.

  export const getRailwayBuildLogs = async ({
    workspacePath,
    deploymentId,
    service,
    environment,
    lines,
    filter,
    json,
  }: GetLogsOptions): Promise<string> => {
    const command = await buildLogCommand({
      type: "build",
      deploymentId,
      service,
      environment,
      lines,
      filter,
      json,
    });
    try {
      await checkRailwayCliStatus();
      const result = await getLinkedProjectInfo({ workspacePath });
      if (!result.success) {
        throw new Error(result.error);
      }
  
      const { output } = await runRailwayCommand(command, workspacePath);
  
      return output;
    } catch (error: unknown) {
      return analyzeRailwayError(error, command);
    }
  };