# Salesforce Mcp Server

> A comprehensive Model Context Protocol (MCP) server that provides seamless Salesforce integration for AI development tools like Claude Desktop, Cline, and other MCP-compatible clients.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jaworjar95-salesforce-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jaworjar95](https://agentstack.voostack.com/s/jaworjar95)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jaworjar95](https://github.com/jaworjar95)
- **Source:** https://github.com/jaworjar95/salesforce-mcp-server

## Install

```sh
agentstack add mcp-jaworjar95-salesforce-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Salesforce MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless Salesforce integration for AI development tools like Claude Desktop, Cline, and other MCP-compatible clients.

## 🚀 Features

### 17 Comprehensive Tools

#### 🔍 Query & Search Tools
- **`execute-soql`** - Execute SOQL queries with auto-bulk switching and pagination
- **`execute-sosl`** - Multi-object search with result aggregation
- **`describe-sobject`** - SObject metadata with intelligent caching

#### ⚡ Apex Development Tools
- **`execute-apex`** - Anonymous Apex execution with debug log capture
- **`run-apex-tests`** - Apex test execution with coverage reporting
- **`get-apex-logs`** - Debug log retrieval with filtering

#### 📊 Data Management Tools
- **`create-record`** - Single/bulk record creation with auto-bulk switching
- **`get-record`** - Record retrieval with field selection
- **`update-record`** - Single/bulk record updates with validation
- **`delete-record`** - Single/bulk record deletion
- **`upsert-record`** - External ID-based upsert operations

#### 🔧 Metadata Tools (Component-Based)
- **`list-metadata-types`** - Discover metadata types
- **`deploy-metadata`** - Deploy individual metadata components (e.g., ApexClass, CustomObject) from files or JSON
- **`deploy-bundle`** - Deploy a metadata bundle (e.g., LWC) from a directory path
- **`retrieve-metadata`** - Retrieve individual metadata components, with an option to save to a file
- **`check-deploy-status`** - Check the status of a deployment

#### 🔗 Connection Tools
- **`test-connection`** - Connection validation and health monitoring

### Key Capabilities

- **🔄 Auto-Bulk Switching** - Intelligent API selection for optimal performance
- **🔐 Dual Authentication** - OAuth2 and Username/Password support
- **⚡ Smart Caching** - 1-hour TTL for SObject metadata
- **🛡️ Type Safety** - Full TypeScript implementation with runtime validation
- **📝 Comprehensive Logging** - Detailed debugging and monitoring
- **🔍 Raw Error Exposure** - Preserve exact Salesforce errors for debugging

## 🚀 Installation

To use with Desktop APP, such as Claude Desktop, Cline, Cursor, and so on, add the MCP server config below.

### On macOS / Linux systems:

Username/Password Authentication

```json
{
  "mcp.servers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_USERNAME": "your-username@company.com",
        "SF_PASSWORD": "your-password",
        "SF_SECURITY_TOKEN": "",
        "SF_LOGIN_URL": "https://login.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}
```

OAuth 2.0 Authentication

```json
{
  "mcp.servers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_CLIENT_ID": "your-oauth2-client-id",
        "SF_CLIENT_SECRET": "your-oauth2-client-secret",
        "SF_REFRESH_TOKEN": "your-refresh-token",
        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}
```

---

### On Windows systems:

Username/Password Authentication

```json
{
  "mcp.servers": {
    "salesforce": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_USERNAME": "your-username@company.com",
        "SF_PASSWORD": "your-password",
        "SF_SECURITY_TOKEN": "",
        "SF_LOGIN_URL": "https://login.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}
```

OAuth 2.0 Authentication

```json
{
  "mcp.servers": {
    "salesforce": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_CLIENT_ID": "your-oauth2-client-id",
        "SF_CLIENT_SECRET": "your-oauth2-client-secret",
        "SF_REFRESH_TOKEN": "your-refresh-token",
        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}
```

### Configuration File Locations

Claude Desktop

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Cline (VS Code)

- **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
- **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

> **⚠️ Important**: After adding or modifying the MCP server configuration, you must restart VS Code for the changes to take effect.

Cursor

- **Windows**: `%USERPROFILE%\.cursor\mcp.json`
- **macOS**: `~/.cursor/mcp.json`
- **Linux**: `~/.cursor/mcp.json`

#### Tool Safety Levels

**✅ Safe for Auto-Approval (`alwaysAllow`)**
- `test-connection` - Connection validation (read-only)
- `execute-soql` - SOQL queries (read-only)
- `describe-sobject` - Metadata inspection (read-only)
- `get-record` - Single record retrieval (read-only)
- `get-apex-logs` - Debug log access (read-only)
- `list-metadata-types` - Metadata type discovery (read-only)

**⚠️ Requires Manual Approval**
- `create-record`, `update-record`, `delete-record`, `upsert-record` - Data modification
- `deploy-metadata` - Metadata deployment
- `execute-apex`, `run-apex-tests` - Code execution
- `execute-sosl` - Search operations (can be resource-intensive)
- `retrieve-metadata` - Metadata retrieval (can be large)

## Authentication

### Username/Password Authentication
1. Obtain your security token from Salesforce Setup → Personal Information → Reset Security Token (only required if your IP is not trusted)
2. Set environment variables as shown in the configuration section
3. Use `https://login.salesforce.com` for production or `https://test.salesforce.com` for sandboxes

> **💡 Security Token**: Only add the security token if Salesforce requires it for your connection. If not leave `SF_SECURITY_TOKEN` empty.

### OAuth2 Authentication
1. Create a Connected App in Salesforce Setup
2. Configure OAuth settings and obtain client credentials
3. Generate a refresh token using the OAuth2 flow
4. Set environment variables as shown in the configuration section

## 🏗️ Architecture

### Core Components
- **Authentication Manager** - Dual OAuth2/Username-Password support
- **Connection Manager** - Singleton pattern with health monitoring
- **Tool Classes** - Organized by functionality (Query, Apex, Data, Metadata)
- **Error Handler** - Comprehensive error formatting with context
- **Cache Manager** - TTL-based caching for performance optimization

### Performance Features
- **Auto-Bulk Switching** - Automatically uses Bulk API for large operations
- **Intelligent Caching** - SObject metadata cached for 1 hour
- **Connection Reuse** - Single connection across all operations
- **Polling Optimization** - Efficient monitoring of long-running operations

## 🧪 Testing

```bash
# Test individual tools
node tests/test-query-tools.js
node tests/test-data-tools.js
node tests/test-apex-tools.js
node tests/test-metadata-tools.js
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 🔗 Related Projects

- [Model Context Protocol](https://github.com/modelcontextprotocol) - The protocol this server implements
- [jsforce](https://github.com/jsforce/jsforce) - Salesforce API library used in this project
- [Claude Desktop](https://claude.ai/desktop) - AI assistant that supports MCP servers
- [Cline](https://github.com/saoudrizwan/claude-dev) - VS Code extension for AI-assisted development

## 👨‍💻 Author

**Jarosław Jaworski**

## 🤖 Development Credits

Part of this implementation was developed with assistance from Claude Sonnet 4 using the Cline VS Code extension, demonstrating the power of AI-assisted development in creating comprehensive developer tools.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jaworjar95](https://github.com/jaworjar95)
- **Source:** [jaworjar95/salesforce-mcp-server](https://github.com/jaworjar95/salesforce-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jaworjar95-salesforce-mcp-server
- Seller: https://agentstack.voostack.com/s/jaworjar95
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.