Magento MCP Server

Instructions

Implementation Reference

• src/actions/auth.ts:12-84 (handler)

  The auth.login handler function that authenticates with Magento using three methods: OAuth 1.0 credentials, integration token, or username/password. It validates inputs, creates a session, and returns authentication details.

  {
    name: 'auth.login',
    description: 'Authenticate with Magento Admin credentials and establish a session.',
    riskTier: RiskTier.Safe,
    requiresAuth: false,
    handler: async (params: Record<string, unknown>, context: ActionContext) => {
      const validated = AuthLoginSchema.parse(params);
  
      const base_url = validated.base_url || process.env.MAGENTO_BASE_URL;
      if (!base_url) {
        return { error: { code: 'VALIDATION_ERROR', message: 'base_url is required — pass it in params or set MAGENTO_BASE_URL env var' } };
      }
  
      // Check for OAuth 1.0 integration credentials first (bypasses 2FA)
      const oauthConsumerKey = (params['oauth_consumer_key'] as string) || process.env.MAGENTO_OAUTH_CONSUMER_KEY;
      const oauthConsumerSecret = (params['oauth_consumer_secret'] as string) || process.env.MAGENTO_OAUTH_CONSUMER_SECRET;
      const oauthToken = (params['oauth_token'] as string) || process.env.MAGENTO_OAUTH_TOKEN;
      const oauthTokenSecret = (params['oauth_token_secret'] as string) || process.env.MAGENTO_OAUTH_TOKEN_SECRET;
  
      if (oauthConsumerKey && oauthConsumerSecret && oauthToken && oauthTokenSecret) {
        const oauthCreds: OAuthCredentials = {
          consumerKey: oauthConsumerKey,
          consumerSecret: oauthConsumerSecret,
          token: oauthToken,
          tokenSecret: oauthTokenSecret,
        };
        const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME || 'integration';
        sessionStore.createOAuth(context.sessionId, base_url, oauthCreds, username);
        return {
          message: 'Login successful (OAuth 1.0 integration)',
          username: username,
          base_url: base_url,
          auth_method: 'oauth',
        };
      }
  
      // Check for integration bearer token (bypasses 2FA)
      const integrationToken = (params['integration_token'] as string) || process.env.MAGENTO_INTEGRATION_TOKEN;
      if (integrationToken) {
        const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME || 'integration';
        sessionStore.create(context.sessionId, base_url, integrationToken, username);
        return {
          message: 'Login successful (integration token)',
          username: username,
          base_url: base_url,
          auth_method: 'integration_token',
        };
      }
  
      // Fall back to username/password login
      const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME;
      if (!username) {
        return { error: { code: 'VALIDATION_ERROR', message: 'username is required — pass it in params or set MAGENTO_ADMIN_USERNAME env var' } };
      }
  
      const password = validated.password || process.env.MAGENTO_ADMIN_PASSWORD;
      if (!password) {
        return { error: { code: 'VALIDATION_ERROR', message: 'password is required — pass it in params or set MAGENTO_ADMIN_PASSWORD env var' } };
      }
  
      const client = new MagentoRestClient(base_url);
      const token = await client.getAdminToken(username, password);
  
      sessionStore.create(context.sessionId, base_url, token, username);
  
      return {
        message: 'Login successful',
        username: username,
        base_url: base_url,
        auth_method: 'admin_token',
      };
    },
  },

• src/validation/schemas.ts:35-39 (schema)

  Zod validation schema for auth_login parameters. Validates that base_url is a valid URL, and username/password are non-empty strings if provided. All fields are optional since they can be sourced from environment variables.

  export const AuthLoginSchema = z.object({
    base_url: z.string().url('base_url must be a valid URL').optional(),
    username: z.string().min(1).optional(),
    password: z.string().min(1).optional(),
  });

• src/index.ts:76-78 (registration)

  Registration loop that converts action names with dots to underscores for MCP tool names. The 'auth.login' action becomes 'auth_login' tool. Calls mcpServer.tool() to register each action as an MCP tool.

  for (const action of allActions) {
    // Convert dots to underscores for MCP tool names (e.g. "auth.login" -> "auth_login")
    const toolName = action.name.replace(/\./g, '_');