# DhanHQ MCP Server
An MCP (Model Context Protocol) server for DhanHQ APIs with OAuth-based authentication for Individual Traders.
## Overview
This server implements the complete three-step DhanHQ authentication flow that generates a JWT access token for API requests. The authentication process involves:
1. **Step 1**: Generate Consent - Creates a temporary session ID
2. **Step 2**: Browser-Based Login - User authenticates with 2FA
3. **Step 3**: Consume Consent - Exchanges tokenId for access token
## Prerequisites
Before you begin, you need to generate your API Key and Secret:
1. Log in to [web.dhan.co](https://web.dhan.co)
2. Navigate to **My Profile** → **'Access DhanHQ APIs'**
3. Toggle to **'API key'**
4. Enter your:
- App name
- Redirect URL (e.g., `http://localhost:3000/callback`)
- Optional Postback URL
Note: Generated API Keys and Secrets are valid for 12 months.
## Setup
### 1. Install Dependencies
```bash
npm install
```
### 2. Configure Environment Variables
Copy `.env.example` to `.env` and fill in your credentials:
```bash
cp .env.example .env
```
```env
DHAN_CLIENT_ID=your_dhan_client_id
DHAN_API_KEY=your_api_key
DHAN_API_SECRET=your_api_secret
REDIRECT_URL=http://localhost:3000/callback
```
### 3. Build the Project
```bash
npm run build
```
## Usage
### Development Mode
```bash
npm run dev
```
### Using MCP Inspector (Recommended for Debugging)
The MCP Inspector provides an interactive interface to test the MCP tools:
```bash
npm run inspector
```
This will:
1. Start the MCP server
2. Open the MCP Inspector in your browser
3. Allow you to call tools and see responses in real-time
## Authentication Flow
### Step 1: Start Authentication
Call the `start_authentication` tool. This will:
- Validate your API credentials
- Create a temporary session (consentAppId)
- Return a login URL
### Step 2: Browser Login
Open the provided login URL in your browser:
- Log in with your Dhan credentials
- Complete 2FA verification (OTP/PIN/Password)
- You'll be redirected to your configured Redirect URL with a `tokenId` parameter
Example redirect URL:
```
http://localhost:3000/callback?tokenId=abc123def456...
```
### Step 3: Complete Authentication
Call the `complete_authentication` tool with the `tokenId` from Step 2:
- Exchanges the tokenId for a JWT access token
- Stores token details (expiry, client info, etc.)
- Returns the access token for use in subsequent API calls
### Check Status
Use `check_auth_status` to view:
- Current authentication state
- Token validity
- Client information
- Token expiry time
## Available MCP Tools
### `start_authentication`
Initiates the DhanHQ authentication flow (Step 1).
- **Input**: None
- **Output**: consentAppId, loginUrl, instructions
### `get_login_instructions`
Gets the login instructions and URL for Step 2.
- **Input**: consentAppId (optional)
- **Output**: loginUrl, detailed instructions
### `complete_authentication`
Completes authentication with the tokenId from Step 2 (Step 3).
- **Input**: tokenId (required)
- **Output**: authToken with accessToken and client details
### `check_auth_status`
Checks the current authentication status.
- **Input**: None
- **Output**: Authentication state and token validity
### `reset_authentication`
Clears the current authentication state.
- **Input**: None
- **Output**: Success message
## API Architecture
- **Framework**: Node.js with TypeScript
- **Protocol**: Model Context Protocol (MCP)
- **Transport**: Stdio
- **Auth API**: DhanHQ OAuth endpoints
- **HTTP Client**: Axios
## Project Structure
```
src/
├── index.ts # MCP server and tool handlers
├── authentication.ts # Authentication logic (3-step flow)
├── config.ts # Configuration management
└── types.ts # TypeScript interfaces
```
## Security Considerations
- API credentials are stored in environment variables
- Access tokens are stored in-memory (session-based)
- For production, use:
- Secure credential storage
- Database for token persistence
- Token refresh mechanisms
- HTTPS for callbacks
- The MCP Inspector output redacts sensitive tokens
## Error Handling
The server includes comprehensive error handling:
- API request validation
- Network error handling
- Configuration validation
- Token expiry checking
## Next Steps
After authentication is working:
1. Add API tools for trading operations
2. Implement token refresh logic
3. Add portfolio/holdings endpoints
4. Implement order placement tools
5. Add market data tools
## Development Notes
- Logs are printed to stderr for debugging
- Authentication state is stored in-memory (lost on restart)
- For production, migrate to persistent storage
- MCP Inspector is recommended for interactive testing and debugging
## License
MIT