# Install Mastra
[EN] Source: https://mastra.ai/docs/getting-started/installation

The `create mastra` CLI command is the quickest way to start a new Mastra project. It walks you through setup and creates example agents, workflows, and tools for you to learn from or adapt.

For more control over setup, or to add Mastra to an existing project, see the [manual installation guide](#install-manually). You can also use [`mastra init`](/reference/cli/mastra#mastra-init) for existing projects.

## Before you start

- You'll need an API key from a [model provider](/models) to complete setup. We suggest starting with [OpenAI](https://platform.openai.com/api-keys), but if you need a provider that doesn't require a credit card, Google's [Gemini](https://aistudio.google.com/app/api-keys) is also an option.
- [Install](https://nodejs.org/en/download) Node.js 20 or later.

## Install with `create mastra`

You can run `create mastra` anywhere on your machine.

The wizard will guide you through setup, create a new directory for your project, and generate a weather agent with example workflows and tools to get you started.

<Tabs>
<TabItem value="npm" label="npm">

```bash copy
npm create mastra@latest
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```bash copy
pnpm create mastra@latest
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash copy
yarn create mastra@latest
```

</TabItem>
<TabItem value="bun" label="bun">

```bash copy
bun create mastra@latest
```

</TabItem>
</Tabs>

:::note

You can use flags with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/docs/getting-started/templates). Read the [CLI reference](/reference/cli/create-mastra) for all options.

:::

### Test your agent

Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at http://localhost:4111.

Try asking about the weather. If your API key is set up correctly, you'll get a response:

<VideoPlayer src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4" />

:::note

If you encounter an error, your API key may not be configured correctly. Double-check your setup and try again. Need more help? [Join our Discord](https://discord.gg/BTYqqHKUrf) and talk to the team directly.

:::

[Studio](/docs/getting-started/studio) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your application using the guides below.

### Next steps

- Read more about [Mastra's features](/docs#why-mastra).
- Integrate Mastra with your frontend framework: [Next.js](/docs/frameworks/web-frameworks/next-js), [React](/docs/frameworks/web-frameworks/vite-react), or [Astro](/docs/frameworks/web-frameworks/astro).
- Build an agent from scratch following one of our [guides](/guides).
- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)!

## Install manually

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

<Steps>

<StepItem>

Create a new project and change directory:

```bash copy
mkdir my-first-agent && cd my-first-agent
```

Initialize a TypeScript project and install the following dependencies:

<Tabs>
<TabItem value="npm" label="npm">

```bash copy
npm init -y
npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod@^4
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```bash copy
pnpm init -y
pnpm add -D typescript @types/node mastra@latest
pnpm add @mastra/core@latest zod@^4
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash copy
yarn init -y
yarn add -D typescript @types/node mastra@latest
yarn add @mastra/core@latest zod@^4
```

</TabItem>
<TabItem value="bun" label="bun">

```bash copy
bun init -y
bun add -d typescript @types/node mastra@latest
bun add @mastra/core@latest zod@^4
```

</TabItem>
</Tabs>

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

```json title="package.json" copy /,/ /"dev": "mastra dev",/ /"build": "mastra build"/
{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "mastra dev",
    "build": "mastra build"
  }
}
```

</StepItem>

<StepItem>

Create a `tsconfig.json` file:

```bash copy
touch tsconfig.json
```

Add the following configuration:

```json title="tsconfig.json" copy
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}
```

:::info

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

:::

</StepItem>

<StepItem>

Create an `.env` file:

```bash copy
touch .env
```

Add your API key:

```bash title=".env" copy
GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
```

:::note

This guide uses Google Gemini, but you can use any supported [model provider](/models), including OpenAI, Anthropic, and more.

:::

</StepItem>

<StepItem>

Create a `weather-tool.ts` file:

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

Add the following code:

```ts title="src/mastra/tools/weather-tool.ts" showLineNumbers copy
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",
    };
  },
});
```

:::info

We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](/docs/agents/using-tools).

:::

</StepItem>

<StepItem>

Create a `weather-agent.ts` file:

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

Add the following code:

```ts title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new 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 },
});
```

</StepItem>

<StepItem>

Create the Mastra entry point and register your agent:

```bash copy
touch src/mastra/index.ts
```

Add the following code:

```ts title="src/mastra/index.ts" showLineNumbers copy
import { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent";

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

</StepItem>

<StepItem>

You can now launch [Studio](/docs/getting-started/studio) and test your agent.

<Tabs>
<TabItem value="npm" label="npm">

```bash copy
npm run dev
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```bash copy
pnpm run dev
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash copy
yarn run dev
```

</TabItem>
<TabItem value="bun" label="bun">

```bash copy
bun run dev
```

</TabItem>
</Tabs>

</StepItem>

</Steps>


---
title: "Mastra Docs Server | Getting Started"
description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
---

import YouTube from "@site/src/components/YouTube-player";