# š Quick Start Guide for DhanHQ MCP Server
## Step 1: Configure Your Credentials
Edit `.env` file with your DhanHQ API credentials:
```bash
DHAN_CLIENT_ID=your_dhan_client_id # Get from web.dhan.co
DHAN_API_KEY=your_api_key # Generated in step 4 of Prerequisites
DHAN_API_SECRET=your_api_secret # Generated in step 4 of Prerequisites
REDIRECT_URL=http://localhost:3000/callback # Must match your configured URL
```
**Where to get these:**
1. Log in to [web.dhan.co](https://web.dhan.co)
2. Go to **My Profile** ā **'Access DhanHQ APIs'**
3. Toggle to **'API key'**
4. Create new API key and configure:
- App name: (e.g., "My Trading App")
- Redirect URL: `http://localhost:3000/callback`
- Optionally add Postback URL
## Step 2: Install Dependencies
```bash
npm install
```
## Step 3: Build the Project
```bash
npm run build
```
## Step 4: Launch MCP Inspector (Recommended for Testing)
```bash
npm run inspector
```
This opens an interactive interface where you can:
- Call MCP tools
- See real-time responses
- Debug authentication flow
- Check token status
## Step 5: Follow the Authentication Flow
### Using MCP Inspector:
1. **Call `start_authentication`**
- This initiates Step 1 of the auth flow
- Returns a `loginUrl` and `consentAppId`
- Example response:
```json
{
"consentAppId": "940b0ca1-3ff4-4476-b46e-03a3ce7dc55d",
"loginUrl": "https://auth.dhan.co/login/consentApp-login?consentAppId=940b0ca1-3ff4-4476-b46e-03a3ce7dc55d",
"message": "Please open this URL in your browser..."
}
```
2. **Open the Login URL in Your Browser** (Step 2)
- Opens the loginUrl in your browser
- Log in with your Dhan credentials
- Complete 2FA verification (OTP/PIN/Password)
- You'll be redirected to: `http://localhost:3000/callback?tokenId=<TOKEN_ID>`
- Copy the `tokenId` from the URL
3. **Call `complete_authentication` with tokenId** (Step 3)
- Pass the tokenId from step 2
- Example input:
```json
{
"tokenId": "abc123def456xyz789..."
}
```
- Receive your access token:
```json
{
"success": true,
"message": "Authentication completed successfully",
"authToken": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"dhanClientId": "1000000001",
"dhanClientName": "JOHN DOE",
"dhanClientUcc": "CEFE4265",
"expiryTime": "2025-09-23T12:37:23",
"givenPowerOfAttorney": true,
"generatedAt": "2024-12-06T10:30:00.000Z"
}
}
```
## Step 6: Check Authentication Status
Call `check_auth_status` to verify your authentication at any time:
```json
{
"authenticated": true,
"hasValidToken": true,
"accessToken": "***REDACTED***",
"authState": {
"consentAppId": "940b0ca1-3ff4-4476-b46e-03a3ce7dc55d",
"consentAppStatus": "GENERATED",
"tokenId": "***REDACTED***",
"clientInfo": {
"dhanClientId": "1000000001",
"dhanClientName": "JOHN DOE",
"dhanClientUcc": "CEFE4265",
"expiryTime": "2025-09-23T12:37:23",
"givenPowerOfAttorney": true,
"generatedAt": "2024-12-06T10:30:00.000Z"
}
}
}
```
## Tools Reference
| Tool | Purpose | Input | Output |
|------|---------|-------|--------|
| `start_authentication` | Initiate auth (Step 1) | None | consentAppId, loginUrl |
| `get_login_instructions` | Get Step 2 instructions | consentAppId (optional) | loginUrl, detailed instructions |
| `complete_authentication` | Complete auth (Step 3) | tokenId | accessToken, client details |
| `check_auth_status` | Check current status | None | Authentication state |
| `reset_authentication` | Clear session | None | Success message |
## Troubleshooting
### Missing Credentials Error
```
Missing required configuration: clientId, apiKey, apiSecret. Please set in .env file.
```
**Solution:** Update your `.env` file with valid DhanHQ credentials.
### Invalid API Key/Secret Error
```
API Error: 401 - Unauthorized
```
**Solution:** Check that your API key and secret are correct in the `.env` file.
### No consentAppId Available
```
No consentAppId available. Please run start_authentication first.
```
**Solution:** Call `start_authentication` before calling other tools.
### Token Expired
The access token is valid for 12 months. When it expires, call `start_authentication` again to generate a new token.
## Development Mode
Run without MCP Inspector:
```bash
npm run dev
```
This will start the server but won't open the inspector UI.
## Next Steps
After authentication is working:
1. Add API tools for trading operations (orders, positions, holdings)
2. Implement market data tools
3. Add portfolio analysis features
4. Build React frontend for UI interaction
5. Deploy to production with proper security measures
---
**Need Help?**
- Check the README.md for detailed documentation
- Review the authentication flow in `src/authentication.ts`
- Enable detailed logging by checking console output in MCP Inspector