Metadata-Version: 2.4
Name: softkad-mcp
Version: 0.1.4
Summary: MCP server that consumes the APIDIAN 2026 API (Softkad DIAN UBL 2.1 e-invoicing)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# softkad-mcp

MCP server for **APIDIAN 2026** — Softkad's DIAN UBL 2.1 e-invoicing service (Colombia).

Connect your AI assistant to the APIDIAN API to:
- Emit electronic invoices, credit notes, debit notes
- Manage companies, certificates, and resolutions
- Query documents, customers, and DIAN tables
- Download XML/PDF files and check DIAN status

| Client | Mode | Config file | Section |
|--------|------|------------|---------|
| **Claude Desktop** | stdio | `claude_desktop_config.json` | [here](#claude-desktop) |
| **ChatGPT Desktop** | stdio | `mcp.json` | [here](#chatgpt-desktop) |
| **Cursor** | SSE | Settings → MCP | [here](#cursor) |
| **Claude Code** | stdio | `.mcp.json` | [here](#claude-code) |
| **Cline** | stdio | `cline_mcp_settings.json` | [here](#cline) |
| **VS Code (Copilot)** | stdio | `settings.json` | [here](#vs-code-copilot) |
| **Windsurf** | stdio | `config.json` | [here](#windsurf) |


---

## Prerequisites

- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
- An **APIDIAN company token** (obtained by registering a company in the platform)

---

## Quick start — Claude Desktop

**macOS:** paste into `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** paste into `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}
```

Replace `TU_TOKEN_AQUI` with your APIDIAN company token. Restart Claude Desktop completely (Cmd+Q → reopen).

### Alternative: token via environment variable (more secure)

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--no-verify-ssl"
      ],
      "env": {
        "APIDIAN_MCP_TOKEN": "TU_TOKEN_AQUI"
      }
    }
  }
}
```

---

## Quick start — ChatGPT Desktop

**macOS:** paste into `~/Library/Application Support/OpenAI/ChatGPT/mcp.json`

**Windows:** paste into `%APPDATA%\OpenAI\ChatGPT\mcp.json`

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}
```

---

## Quick start — Claude Code

[Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp) runs in your terminal and supports MCP via `.mcp.json` in the project root.

Create `.mcp.json` in any project directory (or `~/.mcp.json` for global):

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}
```

Run `claude` from that directory. Type `/mcp` to verify the server loaded.

---

## Quick start — Cline (VS Code extension)

**macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

**Windows:** `%USERPROFILE%\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

```json
{
  "mcpServers": [
    {
      "name": "softkad-apidian",
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ],
      "description": "APIDIAN DIAN e-invoicing"
    }
  ]
}
```

Restart VS Code after saving.

---

## Quick start — VS Code (GitHub Copilot)

**macOS / Windows / Linux:** `settings.json` (Ctrl+Shift+P → "Preferences: Open Settings JSON")

```json
{
  "github.copilot.chat.mcpServers": [
    {
      "name": "softkad-apidian",
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  ]
}
```

> Requires VS Code 1.96+ and GitHub Copilot Chat extension.

---

## Quick start — Windsurf

**macOS:** `~/.config/windsurf/config.json`

**Windows:** `%APPDATA%\Windsurf\config.json`

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}
```

---

## Quick start — Cursor (SSE direct)

**Cursor** supports SSE directly via the UI:

1. Open **Cursor Settings** → **Features** → **MCP**
2. Click **+ Add New MCP Server**
3. Choose **SSE** type
4. Enter the URL: `https://apidian-mcp.softkad.co/sse?token=TU_TOKEN_AQUI`
5. Name it `softkad-apidian` and save

No JSON file editing needed. The token goes directly in the URL query string.

---

## Summary of config file locations

| Client | macOS / Linux | Windows |
|--------|-------------|---------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` |
| ChatGPT Desktop | `~/Library/Application Support/OpenAI/ChatGPT/mcp.json` | `%APPDATA%\OpenAI\ChatGPT\mcp.json` |
| Claude Code | `./.mcp.json` or `~/.mcp.json` | same |
| Cline | `~/.config/Code/User/.../cline_mcp_settings.json` | `%APPDATA%\Code\User\...\cline_mcp_settings.json` |
| VS Code Copilot | `settings.json` (UI or file) | same |
| Windsurf | `~/.config/windsurf/config.json` | `%APPDATA%\Windsurf\config.json` |
| Cursor | UI only (SSE) | UI only (SSE) |

---

## Available tools

### Configuration
- `apidian_company` — Register / update a company (returns token on creation)
- `apidian_company_get` — Query a company by NIT
- `apidian_certificate_upload` — Upload digital certificate `.p12`
- `apidian_register_software` — Register billing software
- `apidian_create_resolution` — Create a resolution

### Catalog & Query
- `apidian_documents_list` — List documents by date/search
- `apidian_customers_list` / `apidian_customer_get` / `apidian_customer_search`
- `apidian_items_list` / `apidian_item_get`
- `apidian_payment_forms` / `apidian_payment_methods` — DIAN tables
- `apidian_information` — Query DIAN taxpayer info (RUT)
- `apidian_download` — Download XML / PDF

### Emission
- `apidian_invoice` — Sales invoice
- `apidian_credit_note` / `apidian_debit_note`
- `apidian_support_document` / `apidian_eqdoc`
- `apidian_payroll` — Payroll document
- `apidian_invoice_mandate` — Invoice with mandate (factoring)

### Status
- `apidian_status_zip` — Query by ZIP_KEY
- `apidian_status_document` — Query by CUFE/CUNE
- `apidian_events_document` — List registered events

### Auxiliary
- `apidian_next_consecutive` — Next consecutive number
- `apidian_whatsapp_send` — Send WhatsApp messages

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `softkad-mcp-bridge was not found` | Missing `--from softkad-mcp` | Add it to args |
| `falta el token` | No `--token` or `APIDIAN_MCP_TOKEN` | Add `--token` or set env |
| `SSL: CERTIFICATE_VERIFY_FAILED` | Let's Encrypt cert not trusted | Add `--no-verify-ssl` |
| Server not showing in Claude | Claude not restarted | Close fully (Cmd+Q) and reopen |
| "Token no válido" | Token expired | Regenerate via company registration |

---

## Developer documentation

For local development, testing, and server deployment:
📖 [Full README on GitHub](https://github.com/finakad/apidiancol-mcp)

---

**Softkad** — [softkad.com](https://softkad.com)
