mcp-cred-hub

Client library for the mcp-cred-hub daemon on macOS.

Single, secure API for MCP servers to retrieve credentials from a local credential hub.

Installation

npm install mcp-cred-hub

Prerequisites

• macOS
• Node.js 18+
• mcp-cred-hub daemon running locally

Quick Start

import { getCredentials } from 'mcp-cred-hub';

async function authenticate() {
  const creds = await getCredentials({
    service: 'github',
    fields: ['token']
  });

  return creds.fields.token;
}

API

getCredentials(options)

Retrieves credentials from the daemon.

Options:

interface GetCredentialsOptions {
  service: string;           // Service name (e.g., "github", "x")
  fields?: string[];         // Specific fields to retrieve (optional)
  clientId?: string;         // Client identifier (for permissions, future)
  profile?: string;          // Profile name (default: "default")
  allowEnvFallback?: boolean; // Fall back to env vars if daemon unavailable
}

Returns:

interface CredentialResponse {
  fields: Record<string, string>;  // Requested credential fields
  metadata: {
    label?: string;                // User-defined label
    expiresAt?: string | null;     // Expiration date (ISO 8601)
    profile: string;               // Profile name
  };
}

Errors:

Throws CredHubError with one of these codes:

• CREDENTIAL_NOT_FOUND - Credential doesn't exist
• DAEMON_NOT_RUNNING - Cannot connect to daemon
• INVALID_REQUEST - Malformed request
• STORAGE_ERROR - Keychain access error
• CONNECTION_ERROR - Socket communication error

Examples

Basic Usage

import { getCredentials } from 'mcp-cred-hub';

const creds = await getCredentials({
  service: 'x',
  fields: ['client_id', 'client_secret']
});

console.log(creds.fields.client_id);

With Environment Fallback

const creds = await getCredentials({
  service: 'github',
  fields: ['token'],
  allowEnvFallback: true  // Falls back to GITHUB_TOKEN env var
});

Error Handling

import { getCredentials, CredHubError } from 'mcp-cred-hub';

try {
  const creds = await getCredentials({ service: 'slack' });
  // Use credentials
} catch (err) {
  if (err instanceof CredHubError) {
    switch (err.code) {
      case 'CREDENTIAL_NOT_FOUND':
        console.log('Please add Slack credentials: mcp-cred add slack');
        break;
      case 'DAEMON_NOT_RUNNING':
        console.log('Start daemon: mcp-cred daemon start');
        break;
      default:
        console.error('Error:', err.message);
    }
  }
}

Configuration

Socket Path

Default: ~/.mcp-cred-hub/socket

Override with environment variable:

export MCP_CRED_HUB_SOCKET=/custom/path/socket

Environment Variable Fallback

When allowEnvFallback: true, the library looks for:

{SERVICE}_{FIELD}

Examples:

• GITHUB_TOKEN
• X_CLIENT_ID
• X_CLIENT_SECRET
• SLACK_BOT_TOKEN

Cursor MCP Configuration

{
  "mcpServers": {
    "myServer": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "MCP_CRED_HUB_SOCKET": "/Users/you/.mcp-cred-hub/socket"
      }
    }
  }
}

Supported Services

Built-in service definitions:

• x (Twitter)
• github
• notion
• slack
• spotify

You can use any service name, even if not pre-defined.

Security

• Connects only to local Unix socket
• No secrets logged or stored by client
• All storage handled by daemon in macOS Keychain
• Socket permissions: user-only (0600)

TypeScript Support

Fully typed with TypeScript definitions included.

License

MIT

Links

• GitHub Repository
• Documentation
• Issues