Manual Installation Guide for Mastra Server

Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the quickstart guide, which achieves the same result using the mastra create command. For existing projects, you can also use mastra init.

If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.

1. Create a new project and change directory:

mkdir my-first-agent && cd my-first-agent

Generate a new package.json file:

• npm
  • pnpm
  • Yarn
  • Bun

npm init

pnpm init

yarn init

bun init

Install the following dependencies:

• npm
  • pnpm
  • Yarn
  • Bun

npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod@^4

pnpm add -D typescript @types/node mastra@latest
pnpm add @mastra/core@latest zod@^4

yarn add --dev typescript @types/node mastra@latest
yarn add @mastra/core@latest zod@^4

bun add --dev typescript @types/node mastra@latest
bun add @mastra/core@latest zod@^4

Add dev and build scripts to your package.json file:

{
  "scripts": {
    "dev": "mastra dev",
    "build": "mastra build"
  }
}

2. Create a tsconfig.json file:

touch tsconfig.json

Add the following configuration:

{
     "compilerOptions": {
       "target": "ES2022",
       "module": "ES2022",
       "moduleResolution": "bundler",
       "esModuleInterop": true,
       "forceConsistentCasingInFileNames": true,
       "strict": true,
       "skipLibCheck": true,
       "noEmit": true,
       "outDir": "dist"
     },
     "include": ["src/**/*"]
}

Mastra requires modern module and moduleResolution settings. Using CommonJS or node will cause resolution errors.

3. Create an .env file:

touch .env

Add your API key:

GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>

This guide uses Google Gemini, but you can use any supported model provider, including OpenAI, Anthropic, and more.

4. Create a weather-tool.ts file:

mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts

Add the following code:

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
     id: 'get-weather',
     description: 'Get current weather for a location',
     inputSchema: z.object({
       location: z.string().describe('City name'),
     }),
     outputSchema: z.object({
       output: z.string(),
     }),
     execute: async () => {
       return {
         output: 'The weather is sunny',
       }
     },
})

5. Create a weather-agent.ts file:

mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts

Add the following code:

import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool'

export const weatherAgent = new Agent({
     id: 'weather-agent',
     name: 'Weather Agent',
     instructions: `
         You are a helpful weather assistant that provides accurate weather information.

Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn't in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

Use the weatherTool to fetch current weather data.
`,
model: 'google/gemini-2.5-pro',
tools: { weatherTool },
})

6. Create the Mastra entry point and register your agent:

touch src/mastra/index.ts

Add the following code:

import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent'

export const mastra = new Mastra({
     agents: { weatherAgent },
})

7. You can now launch Studio and test your agent.

npm run dev

pnpm run dev

yarn dev

bun run dev