# LinkedIn MCP Setup Guide
This guide will walk you through setting up LinkedIn API access and configuring the LinkedIn MCP server for AI integration.
## Table of Contents
1. [LinkedIn App Setup](#linkedin-app-setup)
2. [OAuth Authentication](#oauth-authentication)
3. [Environment Configuration](#environment-configuration)
4. [Local Development](#local-development)
5. [Production Deployment](#production-deployment)
6. [Testing and Validation](#testing-and-validation)
7. [Troubleshooting](#troubleshooting)
## LinkedIn App Setup
### Step 1: Create LinkedIn Developer Account
1. Go to [LinkedIn Developer Portal](https://developer.linkedin.com/)
2. Sign in with your LinkedIn account
3. Accept the LinkedIn API Terms of Use
### Step 2: Create a New App
1. Click "Create App" button
2. Fill in the application details:
- **App name**: Choose a descriptive name (e.g., "My LinkedIn MCP Integration")
- **LinkedIn Page**: Associate with your company page (create one if needed)
- **Privacy policy URL**: Provide a valid URL
- **App logo**: Upload a logo (optional but recommended)
3. Click "Create app"
### Step 3: Configure App Settings
1. In your app dashboard, go to the "Auth" tab
2. Add redirect URLs:
- For local development: `http://localhost:8002/auth/callback`
- For production: `https://your-domain.com/auth/callback`
3. Note your **Client ID** and **Client Secret**
### Step 4: Request API Access
1. Go to the "Products" tab
2. Request access to the following products:
- **Sign In with LinkedIn using OpenID Connect** (usually auto-approved)
- **Share on LinkedIn** (for posting content)
- **Marketing Developer Platform** (for advanced features)
## OAuth Authentication
### Understanding LinkedIn OAuth Flow
LinkedIn uses OAuth 2.0 for authentication. Here's the process:
1. **Authorization Request**: Redirect user to LinkedIn
2. **User Consent**: User grants permissions
3. **Authorization Code**: LinkedIn redirects back with code
4. **Access Token**: Exchange code for access token
5. **API Calls**: Use access token for LinkedIn API requests
### Required Scopes
For the LinkedIn MCP server to work fully, request these scopes:
```
r_liteprofile # Basic profile access
r_emailaddress # Email address
w_member_social # Post to LinkedIn
r_organization_social # Read company data
w_organization_social # Post as organization
```
### Getting Your Access Token
#### Method 1: Manual OAuth Flow (Recommended for Testing)
1. Create the authorization URL:
```
https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=r_liteprofile%20r_emailaddress%20w_member_social
```
2. Visit the URL in your browser and authorize the app
3. Copy the authorization code from the redirect URL
4. Exchange for access token:
```bash
curl -X POST https://www.linkedin.com/oauth/v2/accessToken \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=YOUR_AUTHORIZATION_CODE" \
-d "redirect_uri=YOUR_REDIRECT_URI" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"
```
#### Method 2: Using the FastAPI Client OAuth Helper
```bash
cd mcp-client
python oauth_helper.py --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
```
## Environment Configuration
### Local Development Environment
Create a `.env` file in the `mcp-client` directory:
```bash
# Copy the example file
cp mcp-client/.env.example mcp-client/.env
```
Edit `.env` with your values:
```bash
# LinkedIn API Configuration
LINKEDIN_ACCESS_TOKEN=your_access_token_here
LINKEDIN_CLIENT_ID=your_client_id_here
LINKEDIN_CLIENT_SECRET=your_client_secret_here
# MCP Server Configuration
MCP_SERVER_URL=http://localhost:8888/mcp
API_BASE=http://localhost:8002
# Development Settings
DEBUG=true
LOG_LEVEL=INFO
```
### Production Environment
For Netlify deployment, set environment variables in your Netlify dashboard:
1. Go to your site dashboard
2. Navigate to **Site settings** → **Environment variables**
3. Add the following variables:
- `LINKEDIN_ACCESS_TOKEN`: Your LinkedIn access token
- `LINKEDIN_CLIENT_ID`: Your LinkedIn app client ID
- `LINKEDIN_CLIENT_SECRET`: Your LinkedIn app client secret
## Local Development
### Starting the Development Environment
1. **Install dependencies**:
```bash
# Install Node.js dependencies
npm install
# Install Python dependencies
cd mcp-client
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
2. **Start the LinkedIn MCP infrastructure**:
```bash
cd mcp-client
./start_linkedin.sh
```
This will start:
- Netlify MCP server on `http://localhost:8888/mcp`
- LinkedIn FastAPI client on `http://localhost:8002`
3. **Verify the setup**:
```bash
./check_linkedin_status.sh
```
### Testing with Real LinkedIn Data
```bash
cd mcp-client
python test_linkedin.py
```
This will run comprehensive tests including:
- Server connectivity
- Tool availability
- Authentication validation
- API endpoint testing
## Production Deployment
### Deploying to Netlify
1. **Push to GitHub**:
```bash
git add .
git commit -m "Add LinkedIn MCP server"
git push origin main
```
2. **Connect to Netlify**:
- Go to [Netlify Dashboard](https://app.netlify.com/)
- Click "New site from Git"
- Choose your repository
- Configure build settings:
- Build command: (leave empty)
- Publish directory: `public`
3. **Set Environment Variables**:
- Go to **Site settings** → **Environment variables**
- Add your LinkedIn credentials
4. **Test Deployment**:
```bash
# Test the deployed MCP server
curl -X POST https://your-site-name.netlify.app/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/init","params":{},"id":"1"}'
```
### Using with Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"linkedin-mcp": {
"command": "npx",
"args": [
"mcp-remote@next",
"https://your-site-name.netlify.app/mcp"
],
"env": {
"LINKEDIN_ACCESS_TOKEN": "your_access_token_here"
}
}
}
}
```
## Testing and Validation
### MCP Inspector Testing
```bash
# Test local server
npx @modelcontextprotocol/inspector npx mcp-remote@next http://localhost:8888/mcp
# Test deployed server
npx @modelcontextprotocol/inspector npx mcp-remote@next https://your-site-name.netlify.app/mcp
```
### Manual Testing Examples
#### 1. Get Profile Information
```bash
curl -X POST http://localhost:8002/profile \
-H "Content-Type: application/json" \
-d '{"access_token": "your_token"}'
```
#### 2. Create a LinkedIn Post
```bash
curl -X POST http://localhost:8002/posts \
-H "Content-Type: application/json" \
-d '{
"content": "Hello LinkedIn! Posted via MCP 🚀",
"visibility": "PUBLIC",
"access_token": "your_token"
}'
```
#### 3. Search Companies
```bash
curl -X POST http://localhost:8002/companies/search \
-H "Content-Type: application/json" \
-d '{
"keywords": "Microsoft",
"count": 5,
"access_token": "your_token"
}'
```
### Comprehensive Test Suite
```bash
cd mcp-client
python test_linkedin.py
```
Expected output:
```
🚀 Starting LinkedIn MCP Client Test Suite
==================================================
✅ PASS Health Check
✅ PASS Server Info
✅ PASS List Tools
✅ PASS Profile Mock Auth
...
📊 TEST SUMMARY
Total Tests: 12, Passed: 12 ✅, Failed: 0 ❌
Success Rate: 100.0%
```
## Troubleshooting
### Common Issues
#### 1. Access Token Issues
**Problem**: "LinkedIn access token is required"
**Solution**:
- Verify token is set in environment variables
- Check token hasn't expired (LinkedIn tokens typically last 60 days)
- Ensure correct scopes were requested
#### 2. Rate Limiting
**Problem**: "Rate limit exceeded"
**Solution**:
- Implement exponential backoff
- Check LinkedIn API documentation for limits
- Consider caching responses
#### 3. Scope Permissions
**Problem**: "Insufficient permissions"
**Solution**:
- Request additional scopes in LinkedIn app
- Re-authorize with new scopes
- Check LinkedIn product access approval
#### 4. Local Development Issues
**Problem**: Services won't start
**Solution**:
```bash
# Check ports
lsof -i :8888
lsof -i :8002
# Force stop and restart
./stop_linkedin.sh force
./start_linkedin.sh
```
### Debug Mode
Enable debug logging:
```bash
export DEBUG=true
export LOG_LEVEL=DEBUG
./start_linkedin.sh
```
Check logs:
```bash
tail -f mcp-client/.processes/netlify-dev.log
tail -f mcp-client/.processes/fastapi.log
```
### Getting Help
1. **Check the logs**: Look in `.processes/` directory for detailed error messages
2. **Test connectivity**: Use `check_linkedin_status.sh` for system diagnostics
3. **API Documentation**: Visit `http://localhost:8002/docs` for interactive API testing
4. **LinkedIn Developer Support**: Check LinkedIn developer documentation and forums
## Security Best Practices
1. **Never commit tokens**: Keep access tokens in environment variables, not code
2. **Use HTTPS**: Always use HTTPS in production
3. **Token rotation**: Regularly refresh access tokens
4. **Scope limitation**: Only request necessary scopes
5. **Rate limiting**: Implement proper rate limiting in your applications
## Next Steps
Once you have LinkedIn MCP working:
1. **Integrate with AI assistants**: Add to Claude Desktop, ChatGPT, or other MCP clients
2. **Build automations**: Create workflows for content creation, networking, and lead generation
3. **Monitor usage**: Track API usage and performance
4. **Extend functionality**: Add custom tools for your specific use cases
For more advanced usage, see the [API Reference Documentation](./API_REFERENCE.md) and [Examples](./examples/) directory.
