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

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

2. Configure Environment Variables

Copy .env.example to .env and fill in your credentials:

3. Build the Project

Usage

Development Mode

Using MCP Inspector (Recommended for Debugging)

The MCP Inspector provides an interactive interface to test the MCP tools:

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:

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

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