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:
- Step 1: Generate Consent - Creates a temporary session ID
- Step 2: Browser-Based Login - User authenticates with 2FA
- Step 3: Consume Consent - Exchanges tokenId for access token
Prerequisites
Before you begin, you need to generate your API Key and Secret:
- Log in to web.dhan.co
- Navigate to My Profile → 'Access DhanHQ APIs'
- Toggle to 'API key'
- 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
npm install
2. Configure Environment Variables
Copy .env.example to .env and fill in your credentials:
cp .env.example .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
npm run build
Usage
Development Mode
npm run dev
Using MCP Inspector (Recommended for Debugging)
The MCP Inspector provides an interactive interface to test the MCP tools:
npm run inspector
This will:
- Start the MCP server
- Open the MCP Inspector in your browser
- 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
tokenIdparameter
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:
- Add API tools for trading operations
- Implement token refresh logic
- Add portfolio/holdings endpoints
- Implement order placement tools
- 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