SOQL Queries: Execute powerful SOQL queries with automatic pagination
CRUD Operations: Create, read, update, and delete records across all Salesforce objects
Bulk API: Handle large data operations efficiently with Bulk API 2.0
Composite Requests: Batch multiple operations in a single API call
Object Metadata: Describe Salesforce objects and fields
Rate Limiting: Automatic retry with exponential backoff and API limit tracking
Type Safety: Comprehensive TypeScript types for all Salesforce entities

Installation

npm install
npm run build

Configuration

Create a .env file based on .env.example:

SF_ACCESS_TOKEN=your_oauth2_access_token_here
SF_INSTANCE_URL=https://yourinstance.my.salesforce.com
SF_API_VERSION=v59.0  # Optional, defaults to v59.0

Getting an Access Token

Connected App: Create a Connected App in Salesforce Setup
OAuth Flow: Use OAuth 2.0 to obtain an access token
Refresh Token: Implement token refresh logic for long-running servers

For development, you can use Salesforce CLI:

sfdx force:org:display --verbose -u your_org_alias

Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

Available Tools

Query Tools

salesforce_query: Execute SOQL queries
salesforce_describe_object: Get object metadata

CRUD Tools

salesforce_create_record: Create new records
salesforce_update_record: Update existing records
salesforce_delete_record: Delete records

Bulk Operations

Bulk API 2.0 support for large data operations
Automatic CSV upload and job monitoring

Architecture

Core Components

src/types/index.ts: TypeScript definitions for all Salesforce entities
src/clients/salesforce.ts: REST API client with retry logic and caching
src/server.ts: MCP server with lazy-loaded tool modules
src/main.ts: Entry point with environment validation

Supported Objects

Standard Objects: Account, Contact, Lead, Opportunity, Case, Task, Event
Marketing: Campaign, CampaignMember
Admin: User, UserRole, Profile, PermissionSet
Reports: Report, Dashboard
Files: ContentDocument, ContentVersion, Attachment
Custom Objects: Generic support for any custom object

API Patterns

SOQL Queries

// Simple query
const result = await client.query('SELECT Id, Name FROM Account LIMIT 10');

// Query builder
const soql = client.buildSOQL({
  select: ['Id', 'Name', 'Industry'],
  from: 'Account',
  where: "Industry = 'Technology'",
  orderBy: 'Name ASC',
  limit: 100
});

// Query all (auto-pagination)
const allAccounts = await client.queryAll('SELECT Id, Name FROM Account');

CRUD Operations

// Create
const result = await client.createRecord('Account', {
  Name: 'Acme Corp',
  Industry: 'Technology'
});

// Update
await client.updateRecord('Account', accountId, {
  Phone: '555-1234'
});

// Delete
await client.deleteRecord('Account', accountId);

Bulk API

// Create bulk job
const job = await client.createBulkJob({
  object: 'Account',
  operation: 'insert'
});

// Upload CSV data
await client.uploadBulkData(job.id, csvData);

// Close job
await client.closeBulkJob(job.id);

Error Handling

The client includes:

Automatic retry with exponential backoff (3 retries)
Rate limit detection and handling
Structured error responses
API limit tracking via Sforce-Limit-Info header

Resources

License

MIT