# Quick Start Guide - First-Time User Guide
This guide will walk you through all the configuration steps one by one. Even if you're using this project for the first time, you'll have no problem!
## 📋 Complete Process Overview
```
1. Create an integration in Notion
2. Configure the project's .env file
3. Configure MCP service in Claude Desktop
4. Build and run the project
5. Test the connection
```
---
## Step 1: Notion Integration Setup
### 1.1 Create Notion Integration Token
1. Open [Notion Integrations page](https://www.notion.so/my-integrations)
2. Click the **"Create new integration"** button
3. Fill out the form:
- **Name**: Give your integration a name, such as `AI QA Tracker MCP Server`
- **Logo**: Optional, add an icon (recommend using 🤖 or related emoji)
- **Associated workspace**: Select your Notion workspace
4. Click **"Submit"** to create
5. Copy the **"Internal Integration Token"** (looks like `ntn_...`)
6. ⚠️ **Keep this token safe**, do not share it with others
### 1.2 Grant Integration Permissions
1. In your Notion workspace, find the page where you want to save AI Q&A
2. Click **"..."** (More options) in the top-right corner of that page
3. Scroll down to **"Add connections"**
4. Search for the integration name you just created (e.g., `AI QA Tracker MCP Server`)
5. Select it and confirm
### 1.3 Get Parent Page ID
This is the ID of the Notion page where you want to create a database.
1. Open the Notion page where you want to save the database
2. Check the URL in your browser address bar, format like:
```
https://www.notion.so/username/1cde7359-c8f9-804e-bf30-cd6362086e1e?v=...
```
3. Copy the UUID portion (after `/` and before `?`):
```
1cde7359-c8f9-804e-bf30-cd6362086e1e
```
> 💡 **Tip**: You can also find this ID in your browser's DevTools, or just copy the page link and the UUID will be in it.
---
## Step 2: Project Local Configuration
### 2.1 Configure .env File
Create or edit the `.env` file in the project root directory:
```bash
# Edit or create .env file
nano .env
```
Fill in the following content (replace with your actual values):
```env
# Token copied from Notion integration page
NOTION_API_TOKEN=ntn_your_token_here
# Notion page ID where you want to create the database
NOTION_PARENT_PAGE_ID=1cde7359-c8f9-804e-bf30-cd6362086e1e
# (Optional) If you already have a database, fill in the database ID
NOTION_DATABASE_ID=2f9e7359-c8f9-8128-a124-fe5996326258
```
> ⚠️ **Important**: The `.env` file is already in `.gitignore`, so it won't be committed to Git, and your token is safe.
### 2.2 Project Structure Explanation
```
notion-mcp-server/
├── src/
│ ├── index.ts ← Main entry point of MCP server
│ ├── config.ts ← Configuration loading and validation
│ ├── types.ts ← TypeScript type definitions
│ ├── setup-database.ts ← Database initialization script
│ ├── test-notion.ts ← Notion connection test
│ ├── mock-test.ts ← Mock test (no real Token needed)
│ └── test.ts ← MCP server test
├── dist/ ← Compiled output directory (auto-generated)
├── .env ← Your config file (don't commit to Git)
├── .env.example ← Config template (can be committed)
├── tsconfig.json ← TypeScript configuration
├── package.json ← Project dependencies
└── README.md ← Project documentation
```
---
## Step 3: Configure MCP Service in Claude Desktop
### 3.1 Find Claude Desktop Config File
Depending on your operating system, find `claude_desktop_config.json`:
**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```
### 3.2 Edit the Config File
Open the config file with a text editor and find or create the `mcpServers` section:
```json
{
"mcpServers": {
"notion-server": {
"command": "node",
"args": [
"/Users/itsyuimorii/Documents/githubnew/notion-mcp-server/dist/index.js"
],
"env": {
"NOTION_API_TOKEN": "ntn_your_token_here",
"NOTION_PARENT_PAGE_ID": "1cde7359-c8f9-804e-bf30-cd6362086e1e",
"NOTION_DATABASE_ID": "2f9e7359-c8f9-8128-a124-fe5996326258"
}
}
}
}
```
**Parts that need to be modified:**
- ✏️ **Path in args**: Change to your project path (followed by `/dist/index.js`)
- ✏️ **Three values in env**: Fill in the Token and IDs you obtained from Notion
### 3.3 Why Do We Need index.js?
```
What is dist/index.js?
│
├─ src/index.ts is the TypeScript source file
├─ After compilation → dist/index.js (JavaScript version)
│
└─ Why Claude Desktop needs index.js:
├─ Claude Desktop runs a Node.js process
├─ Node.js directly executes .js files, cannot execute .ts files
├─ TypeScript needs to be compiled to JavaScript
└─ dist/ directory is the compilation output
```
**Complete Lifecycle:**
```
Development: src/index.ts (code you write)
↓ npm run build (compilation)
Production: dist/index.js (Claude Desktop executes)
```
---
## Step 4: Build and Run the Project
### 4.1 Install Dependencies
```bash
cd /Users/itsyuimorii/Documents/githubnew/notion-mcp-server
npm install
```
This will install all necessary packages:
- `@modelcontextprotocol/sdk` - MCP protocol library
- `@notionhq/client` - Notion API client
- `dotenv` - Environment variable loader
- etc.
### 4.2 Build the Project (Generate dist/index.js)
```bash
npm run build
```
**What Happens?**
```
npm run build will execute the configuration in tsconfig.json:
├─ Read all .ts files in src/
├─ Perform type checking according to TypeScript rules
├─ Compile to JavaScript
└─ Output to dist/ directory
Output example:
dist/
├── index.js ← Claude Desktop needs this
├── config.js
├── types.js
├── setup-database.js
└── ...other files
```
### 4.3 Local Testing (Optional)
Before formally configuring Claude Desktop, you can test locally:
```bash
# Test Notion connection
npm run test-notion
# Run mock test (no real Notion database needed)
npm run test
# Start development mode (with auto-reload)
npm run dev
```
---
## Step 5: Verify Configuration
### 5.1 Configuration Checklist
After configuration is complete, check the following items:
- [ ] ✅ Notion integration created and token obtained
- [ ] ✅ Integration permission added in Notion page
- [ ] ✅ Parent Page ID obtained
- [ ] ✅ Project `.env` file configured
- [ ] ✅ Claude Desktop config file updated
- [ ] ✅ Ran `npm install`
- [ ] ✅ Ran `npm run build` to generate dist/index.js
### 5.2 Test Claude Desktop Connection
1. Close and reopen Claude Desktop application
2. Click the **"MCP"** icon below the conversation box (or check connection status)
3. You should see `notion-server` connected
4. Try asking in a conversation:
```
"Can you save this to my Notion database:
Q: What is MCP?
A: MCP stands for Model Context Protocol..."
```
---
Any questions? You can always refer to this guide! ✨
