🎙️ Djelia MCP Server

An MCP server for Djelia — bring Bambara transcription, translation, and text-to-speech to any LLM.

Built with FastMCP v3 · Python 3.11+ · uv-managed

</div>

---

✨ Overview

Djelia is a linguistic-AI platform focused on African languages — currently Bambara (bam_Latn), with translation bridging to French (fra_Latn) and English (eng_Latn).

This server wraps the Djelia REST API behind the Model Context Protocol, so any MCP-compatible client (Claude Desktop, Cursor, Cline, your own agent) can call Djelia's models as native tools — no SDK glue, no HTTP plumbing in your prompt.

What you get

| # | Tool | Direction | V1 / V2 | Returns | |---|------|-----------|---------|---------| | 1 | list_supported_languages | — | — | JSON list | | 2 | translate | text → text | v1 | translated text | | 3 | transcribe | audio → text | v2 | text + segment timing | | 4 | text_to_speech | text → audio | v2 | audio content block |

Design note: V2 APIs are exposed for transcription and TTS because they supersede V1 (richer voices via description, format control). True /stream endpoints are omitted — MCP is request/response, so we aggregate the stream inside the tool. Add raw streaming tools only if a use case needs them.

---

🏗️ Architecture

flowchart LR
    subgraph Client["MCP Client"]
        LLM["LLM / Agent<br/>(Claude, Cursor, …)"]
    end

    subgraph Server["djelia-mcp-server (this repo)"]
        MCP["FastMCP Server<br/><i>4 tools, stdio · sse · http</i>"]
        HANDLERS["Tool Handlers<br/>translate · transcribe · tts"]
        HTTP["httpx.AsyncClient<br/><i>x-api-key header</i>"]
        MCP --> HANDLERS --> HTTP
    end

    subgraph Djelia["Djelia Cloud API"]
        T1["/v1/translate"]
        T2["/v2/transcribe"]
        T3["/v2/tts"]
    end

    LLM -- "MCP JSON-RPC" --> MCP
    HTTP -- "HTTPS" --> T1
    HTTP -- "HTTPS" --> T2
    HTTP -- "HTTPS" --> T3

Key design choices

One shared HTTP client — x-api-key header injected once per request; key read from DJELIA_API_KEY env var.
base64 for audio input — MCP payloads are JSON; audio bytes travel as base64 so it works across any client. A magic-byte sniffer (_guess_ext) recovers the right file extension for the multipart upload.
Audio output as a content block — FastMCP's Audio helper returns a proper MCP audio block (clients receive it base64-encoded).

---

🔧 How each tool works

1 · `list_supported_languages`

Returns the language codes you'll pass to translate.

sequenceDiagram
    participant C as Client
    participant S as MCP Server
    participant D as Djelia API
    C->>S: list_supported_languages()
    S->>D: GET /api/v1/models/translate/supported-languages
    D-->>S: [{code, name}, ...]
    S-->>C: structured list

2 · `translate`

sequenceDiagram
    participant C as Client
    participant S as MCP Server
    participant D as Djelia API
    C->>S: translate(source, target, text)
    S->>D: POST /api/v1/models/translate (JSON)
    D-->>S: { "text": "<translated>" }
    S-->>C: structured dict

Parameters

| Name | Type | Values | |---|---|---| | source | enum | bam_Latn · fra_Latn · eng_Latn | | target | enum | bam_Latn · fra_Latn · eng_Latn | | text | string | the text to translate |

3 · `transcribe` (Bambara audio → text)

The tool decodes base64 → sniffs the format → uploads as multipart to the V2 transcription endpoint.

sequenceDiagram
    participant C as Client
    participant S as MCP Server
    participant D as Djelia API
    C->>S: transcribe(audio_base64)
    S->>S: base64decode + guess_ext (mp3/wav/m4a/ogg)
    S->>D: POST /api/v2/models/transcribe (multipart)
    alt single text response
        D-->>S: { "text": "..." }
    else segmented response
        D-->>S: [{ text, start, end }, ...]
    end
    S-->>C: ToolResult (structured + text)

4 · `text_to_speech` (text → Bambara audio)

sequenceDiagram
    participant C as Client
    participant S as MCP Server
    participant D as Djelia API
    C->>S: text_to_speech(text, description, format)
    S->>D: POST /api/v2/models/tts (JSON)
    D-->>S: binary audio bytes
    S-->>C: Audio content block (base64)

Parameters

| Name | Type | Values | |---|---|---| | text | string | text to synthesize | | description | string | voice style, e.g. "calm male voice, slow pace" | | format | enum | mp3 (default) · wav · wav_8k · ulaw_8k |

---

🚀 Quickstart

1 · Prerequisites

uv installed
A Djelia API key — get one at <https://console.djelia.cloud>

2 · Install dependencies

git clone <your-repo-url> djelia-mcp-server
cd djelia-mcp-server
uv sync

3 · Set your API key

cp .env.example .env
# edit .env:
#   DJELIA_API_KEY=your_key_here

The server reads DJELIA_API_KEY from the environment. It fails fast with a clear message if the key is missing.

---

🌐 Transports

FastMCP supports three transports. Pick the one your client expects.

flowchart TB
    subgraph "Transport decision"
        STDIO["stdio<br/><b>default</b><br/>Claude Desktop, CLI agents"]
        SSE["sse<br/><b>legacy</b><br/>older MCP clients"]
        HTTP["http / streamable-http<br/><b>recommended for network</b>"]
    end
    STDIO -. "stdin/stdout" .-> Srv["FastMCP Server"]
    SSE   -. "HTTP + EventSource<br/>GET /sse/" .-> Srv
    HTTP  -. "HTTP POST<br/>POST /mcp/" .-> Srv

| Mode | Command | Endpoint | |---|---|---| | stdio (default) | uv run fastmcp run server.py | — | | sse (legacy) | uv run fastmcp run server.py -t sse -p 8000 | http://127.0.0.1:8000/sse/ | | http | uv run fastmcp run server.py -t http -p 8000 | http://127.0.0.1:8000/mcp/ | | streamable-http | uv run fastmcp run server.py -t streamable-http -p 8000 | http://127.0.0.1:8000/mcp/ |

Override host/port with --host / -p. See all options: uv run fastmcp run --help.

Direct Python (without the `fastmcp` CLI)

Transport is read from DJELIA_TRANSPORT (stdio | sse | http):

DJELIA_TRANSPORT=sse DJELIA_HOST=127.0.0.1 DJELIA_PORT=8000 uv run python server.py

---

🤝 Client configuration

Claude Desktop / Cursor (stdio)

Drop this into your MCP client config:

{
  "mcpServers": {
    "djelia": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/djelia-mcp-server",
        "fastmcp",
        "run",
        "server.py"
      ],
      "env": {
        "DJELIA_API_KEY": "your_api_key"
      }
    }
  }
}

Remote / networked client (SSE or HTTP)

Run the server with -t sse or -t http, then point your client at the endpoint (e.g. http://your-host:8000/mcp/).

---

🗂️ Project layout

djelia-mcp-server/
├── server.py         # all 4 tools + httpx client + transport switch
├── pyproject.toml    # uv project (fastmcp + httpx)
├── .env.example      # DJELIA_API_KEY template
├── .gitignore
└── README.md

One file of code — by design. Tools are co-located because they share one client and one concern (calling Djelia).

---

🧪 Verifying it works

Smoke-test that all tools register and the server boots on every transport:

# list registered tools
uv run python -c "import asyncio, server; \
  [print(' -', t.name) for t in asyncio.run(server.mcp.list_tools())]"

# boot a transport
uv run fastmcp run server.py -t sse -p 8000

You should see 4 tools listed, and the FastMCP banner with transport 'sse' followed by Uvicorn running.

---

📚 References

Djelia API docs — <https://djelia.cloud/redoc>
Djelia console (get an API key) — <https://console.djelia.cloud>
FastMCP — <https://gofastmcp.com>
Model Context Protocol — <https://modelcontextprotocol.io>

---

📝 License

MIT

Djelia MCP Server