Technologikal/firefish-mcp

Firefish MCP Server

A Model Context Protocol (MCP) server for integrating with the Firefish Recruitment CRM API. This server enables AI assistants like Claude to interact with your Firefish instance to manage candidates, companies, contacts, jobs, and placements.

Features

• Candidate Management: Search, view, create, and update candidate records
• Company Management: Search, view, create, and update company records
• Contact Management: Search, view, create, and update contact records
• Job Listings: Search and view job postings
• Placement Tracking: Search and view placements and offers
• OAuth Authentication: Secure API access using OAuth 2.0

Prerequisites

• Python 3.10 or higher
• Firefish CRM account with API access
• OAuth credentials (client ID and client secret) from Firefish

Setup

1. Install Dependencies

Using uv (recommended):

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Using pip:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

2. Configure Environment Variables

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

cp .env.example .env

Edit .env with your actual credentials:

FIREFISH_API_URL=https://api.firefishsoftware.com
FIREFISH_CLIENT_ID=your_client_id_here
FIREFISH_CLIENT_SECRET=your_client_secret_here
FIREFISH_OAUTH_TOKEN_URL=https://your-instance.firefishsoftware.com/oauth/token
FIREFISH_INSTANCE_URL=https://your-instance.firefishsoftware.com

3. Configure Claude for Desktop

Add the server to your Claude for Desktop configuration:

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

{
  "mcpServers": {
    "firefish": {
      "command": "python",
      "args": ["-m", "firefish_mcp.server"],
      "env": {
        "FIREFISH_API_URL": "https://api.firefishsoftware.com",
        "FIREFISH_CLIENT_ID": "your_client_id",
        "FIREFISH_CLIENT_SECRET": "your_client_secret",
        "FIREFISH_OAUTH_TOKEN_URL": "https://your-instance.firefishsoftware.com/oauth/token"
      }
    }
  }
}

Alternatively, you can use the absolute path to your virtual environment:

{
  "mcpServers": {
    "firefish": {
      "command": "/absolute/path/to/firefish-project/.venv/bin/python",
      "args": ["-m", "firefish_mcp.server"]
    }
  }
}

Available Tools

The MCP server provides the following tools for Claude:

Candidates

• search_candidates - Search for candidates with optional filters
• get_candidate - Get detailed candidate information by ID
• create_candidate - Create a new candidate record
• update_candidate - Update an existing candidate

Companies

• search_companies - Search for companies with optional filters
• get_company - Get detailed company information by ID
• create_company - Create a new company record
• update_company - Update an existing company

Contacts

• search_contacts - Search for contacts with optional filters
• get_contact - Get detailed contact information by ID
• create_contact - Create a new contact record
• update_contact - Update an existing contact

Jobs

• search_jobs - Search for job listings with optional filters
• get_job - Get detailed job information by ID

Placements

• search_placements - Search for placements/offers with optional filters

Actions & Statistics (PLACEHOLDER)

Note: The following tools are placeholders awaiting confirmation from Firefish support regarding actual API endpoints and data structures.

Actions

• search_actions - Search for user actions/activities with optional filters
• get_user_actions - Get actions for a specific user
• get_team_actions - Get actions for a specific team

Statistics

• get_user_statistics - Get activity statistics for a user
• get_team_statistics - Get performance statistics for a team
• get_activity_summary - Get overall activity summary/dashboard statistics

Communications

• search_communications - Search for communications with optional filters

These tools are currently implemented but may return errors until the correct endpoint paths are confirmed with Firefish. See CLAUDE.md for instructions on updating these endpoints once documentation is received.

Development

Running Tests

pytest

Code Formatting

black src/

Linting

ruff check src/

API Documentation

For detailed Firefish API documentation, visit: https://fishtank.firefishsoftware.com/firefish-api-documentation

License

MIT License - see LICENSE file for details